Sprinkles: Add support for container query conditions (#812)

Author: markdalgleish

.changeset/fluffy-steaks-yell.md

@@ -0,0 +1,36 @@
+---
+'@vanilla-extract/sprinkles': minor
+---
+
+Add support for container query conditions
+
+**Example usage**
+
+```ts
+import {
+  createContainer,
+  style
+} from '@vanilla-extract/css';
+import { defineProperties } from '@vanilla-extract/sprinkles';
+
+const containerName = createContainer();
+
+export const container = style({
+  containerName,
+  containerType: 'size'
+});
+
+const containerProperties = defineProperties({
+  conditions: {
+    small: {},
+    medium: {
+      '@container': `${containerName} (min-width: 768px)`
+    },
+    large: {
+      '@container': `${containerName} (min-width: 1024px)`
+    }
+  },
+  defaultCondition: 'small'
+  // etc.
+});
+```

fixtures/sprinkles/src/index.ts

@@ -4,25 +4,28 @@ import {
   normalizeResponsiveValue,
   preComposedSprinkles,
   preComposedSprinklesUsedInSelector,
+  container,
 } from './styles.css';
 import testNodes from '../test-nodes.json';
 
 function render() {
   document.body.innerHTML = `
-  <div id="${testNodes.root}" class="${sprinkles({
-    display: normalizeResponsiveValue('block').mobile,
-    paddingTop: mapResponsiveValue(
-      {
-        mobile: 'small',
-        desktop: 'medium',
-      } as const,
-      (x) => x,
-    ),
-  })}"> 
-    Sprinkles
+  <div id="${testNodes.root}" class="${container}">
+    <div class="${sprinkles({
+      display: normalizeResponsiveValue('block').mobile,
+      paddingTop: mapResponsiveValue(
+        {
+          mobile: 'small',
+          desktop: 'medium',
+        } as const,
+        (x) => x,
+      ),
+    })}">
+      Sprinkles
+    </div>
+    <div class="${preComposedSprinkles}">Precomposed sprinkles</div>
+    <div class="${preComposedSprinklesUsedInSelector}">Precomposed Sprinkles Used In Selector</div>
   </div>
-  <div class="${preComposedSprinkles}">Precomposed sprinkles</div>
-  <div class="${preComposedSprinklesUsedInSelector}">Precomposed Sprinkles Used In Selector</div>
 `;
 }
 

fixtures/sprinkles/src/styles.css.ts

@@ -1,4 +1,9 @@
-import { globalStyle, createVar } from '@vanilla-extract/css';
+import {
+  globalStyle,
+  createVar,
+  createContainer,
+  style,
+} from '@vanilla-extract/css';
 import {
   defineProperties,
   createSprinkles,
@@ -9,14 +14,23 @@ import {
 const alpha = createVar();
 const textAlpha = createVar();
 
+const containerName = createContainer();
+
+export const container = style({
+  containerName,
+  containerType: 'size',
+});
+
 const responsiveProperties = defineProperties({
   defaultCondition: 'mobile',
   conditions: {
     mobile: {},
     tablet: {
+      '@container': `${containerName} (min-width: 768px)`,
       '@media': 'screen and (min-width: 768px)',
     },
     desktop: {
+      '@container': `${containerName} (min-width: 1024px)`,
       '@media': 'screen and (min-width: 1024px)',
     },
     darkDesktop: {
@@ -87,6 +101,10 @@ export const preComposedSprinklesUsedInSelector = sprinkles({
   paddingTop: 'medium',
 });
 
-globalStyle(`body > ${preComposedSprinklesUsedInSelector}`, {
+globalStyle('body', {
+  margin: 0,
+});
+
+globalStyle(`body ${preComposedSprinklesUsedInSelector}`, {
   background: 'red',
 });

packages/sprinkles/src/index.ts

@@ -16,21 +16,14 @@ import { SprinklesProperties, ResponsiveArrayConfig } from './types';
 export { createNormalizeValueFn, createMapValueFn } from './createUtils';
 export type { ConditionalValue, RequiredConditionalValue } from './createUtils';
 
-interface Condition {
-  '@media'?: string;
-  '@supports'?: string;
-  selector?: string;
-}
+type ConditionKey = '@media' | '@supports' | '@container' | 'selector';
+type Condition = Partial<Record<ConditionKey, string>>;
 
 type BaseConditions = { [conditionName: string]: Condition };
 
 type AtomicProperties = {
   [Property in keyof CSSProperties]?:
-    | Record<
-        string,
-        | CSSProperties[Property]
-        | Omit<StyleRule, 'selectors' | '@media' | '@supports'>
-      >
+    | Record<string, CSSProperties[Property] | Omit<StyleRule, ConditionKey>>
     | ReadonlyArray<CSSProperties[Property]>;
 };
 
@@ -262,6 +255,14 @@ export function defineProperties(options: any): any {
             };
           }
 
+          if (condition['@container']) {
+            styleValue = {
+              '@container': {
+                [condition['@container']]: styleValue,
+              },
+            };
+          }
+
           if (condition['@media']) {
             styleValue = {
               '@media': {

site/docs/packages/sprinkles.md

@@ -383,7 +383,9 @@ const responsiveProperties = defineProperties({
 
 ### conditions
 
-Define a set of media/feature queries for the provided properties.
+Define a set of media/feature/container queries for the provided properties.
+
+For example, properties can be scoped to media queries.
 
 ```ts
 // sprinkles.css.ts
@@ -417,6 +419,40 @@ const properties = defineProperties({
 });
 ```
 
+Properties can also be scoped to container queries.
+
+> 🚧  Ensure your target browsers [support container queries]. Vanilla-extract supports the [container query syntax] but does not polyfill the feature in unsupported browsers.
+
+```ts
+// sprinkles.css.ts
+import {
+  createContainer,
+  style
+} from '@vanilla-extract/css';
+import { defineProperties } from '@vanilla-extract/sprinkles';
+
+const containerName = createContainer();
+
+export const container = style({
+  containerName,
+  containerType: 'size'
+});
+
+const containerProperties = defineProperties({
+  conditions: {
+    small: {},
+    medium: {
+      '@container': `${containerName} (min-width: 768px)`
+    },
+    large: {
+      '@container': `${containerName} (min-width: 1024px)`
+    }
+  },
+  defaultCondition: 'small'
+  // etc.
+});
+```
+
 ### defaultCondition
 
 Defines which condition(s) should be used when a non-conditional value is requested, e.g. `sprinkles({ display: 'flex' })`.
@@ -735,3 +771,5 @@ const e: ResponsiveAlign = { desktop: 'center' };
 
 [tailwind]: https://tailwindcss.com
 [styled system]: https://styled-system.com
+[support container queries]: https://caniuse.com/css-container-queries
+[container query syntax]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Container_Queries