Add Circular Selectors section to docs (#1096)

* Add tests for getter selector

* Add Circular Selectors case to docs

* Fix typo

Co-authored-by: Paul Grau <[email protected]>

* Fix lint

---------

Co-authored-by: Paul Grau <[email protected]>

Author: aspirisen

packages/css/src/transformCss.test.ts

@@ -971,6 +971,50 @@ describe('transformCss', () => {
     `);
   });
 
+  it('should handle getter selectors', () => {
+    expect(
+      transformCss({
+        composedClassLists: [],
+        localClassNames: ['testClass', 'parentClass'],
+        cssObjs: [
+          {
+            type: 'local',
+            selector: 'testClass',
+            rule: {
+              color: 'red',
+              get selectors() {
+                return {
+                  '&:nth-child(3)': {
+                    color: 'blue',
+                  },
+                  'parentClass > div > span ~ &.someGlobalClass:hover': {
+                    background: 'green',
+                  },
+                  'parentClass&': {
+                    background: 'black',
+                  },
+                };
+              },
+            },
+          },
+        ],
+      }).join('\n'),
+    ).toMatchInlineSnapshot(`
+      .testClass {
+        color: red;
+      }
+      .testClass:nth-child(3) {
+        color: blue;
+      }
+      .parentClass > div > span ~ .testClass.someGlobalClass:hover {
+        background: green;
+      }
+      .parentClass.testClass {
+        background: black;
+      }
+    `);
+  });
+
   it('should handle complex selectors within media queries', () => {
     expect(
       transformCss({

site/docs/overview/styling.md

@@ -237,6 +237,35 @@ globalStyle(`${parent} a[href]`, {
 });
 ```
 
+### Circular Selectors
+
+If your selectors are dependent on each other you can use [getters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get) to define them:
+
+```ts compiled
+// styles.css.ts
+import { style } from '@vanilla-extract/css';
+
+export const child = style({
+  background: 'blue',
+  get selectors() {
+    return {
+      [`${parent} &`]: {
+        color: 'red'
+      }
+    };
+  }
+});
+
+export const parent = style({
+  background: 'yellow',
+  selectors: {
+    [`&:has(${child})`]: {
+      padding: 10
+    }
+  }
+});
+```
+
 ## Container Queries
 
 Container queries work the same as [media queries] and are nested inside the `@container` key.

tests/compiler/compiler.vitest.test.ts

@@ -271,6 +271,35 @@ describe('compiler', () => {
     `);
   });
 
+  test('getter selector', async () => {
+    const compiler = compilers.default;
+
+    const cssPath = path.join(__dirname, 'fixtures/selectors/getter.css.ts');
+    const output = await compiler.processVanillaFile(cssPath);
+    const { css } = await compiler.getCssForFile(cssPath);
+
+    expect(output.source).toMatchInlineSnapshot(`
+      "import 'fixtures/selectors/getter.css.ts.vanilla.css';
+      export var child = 'getter_child__ux95kn0';
+      export var parent = 'getter_parent__ux95kn1';"
+    `);
+
+    expect(css).toMatchInlineSnapshot(`
+      ".getter_child__ux95kn0 {
+        background: blue;
+      }
+      .getter_parent__ux95kn1 .getter_child__ux95kn0 {
+        color: red;
+      }
+      .getter_parent__ux95kn1 {
+        background: yellow;
+      }
+      .getter_parent__ux95kn1:has(.getter_child__ux95kn0) {
+        padding: 10px;
+      }"
+    `);
+  });
+
   afterAll(async () => {
     await Promise.allSettled(
       Object.values(compilers).map((compiler) => compiler.close()),

tests/compiler/fixtures/selectors/getter.css.ts

@@ -0,0 +1,21 @@
+import { style } from '@vanilla-extract/css';
+
+export const child = style({
+  background: 'blue',
+  get selectors() {
+    return {
+      [`${parent} &`]: {
+        color: 'red',
+      },
+    };
+  },
+});
+
+export const parent = style({
+  background: 'yellow',
+  selectors: {
+    [`&:has(${child})`]: {
+      padding: 10,
+    },
+  },
+});