Sprinkles: Clean up public API and document on site (#360)

Author: michaeltaranto

.changeset/nervous-pumpkins-matter.md

@@ -0,0 +1,36 @@
+---
+'@vanilla-extract/sprinkles': minor
+---
+
+Clean up public API, deprecating old API names. Also adding sprinkles to the docs site and using `sprinkles` in favour of `atoms` for the canoncial examples.
+
+API changes include:
+- Rename `createAtomicStyles` to `defineProperties`, `createAtomicStyles` is now deprecated
+- Rename `createAtomsFn` to `createSprinkles`, `createAtomsFn` is now deprecated
+- Rename `AtomicStyles` type to `SprinklesProperties`, `AtomicStyles` is now deprecated
+
+### Migration Guide
+
+```diff
+-import { createAtomicStyles, createAtomsFn } from '@vanilla-extract/sprinkles';
++import { defineProperties, createSprinkles } from '@vanilla-extract/sprinkles';
+
+-const responsiveProperties = createAtomicStyles({
++const responsiveProperties = defineProperties({
+  conditions: {
+    mobile: {},
+    tablet: { '@media': 'screen and (min-width: 768px)' },
+    desktop: { '@media': 'screen and (min-width: 1024px)' }
+  },
+  defaultCondition: 'mobile',
+  properties: {
+    display: ['none', 'block', 'flex'],
+    flexDirection: ['row', 'column'],
+    padding: space
+    // etc.
+  }
+});
+
+-export const sprinkles = createAtomsFn(responsiveProperties);
++export const sprinkles = createSprinkles(responsiveProperties);
+```

README.md

@@ -74,7 +74,7 @@ document.write(`
 
 ---
 
-Want to work at a higher level while maximising style re-use? Check out  🍨 [Sprinkles](https://github.com/seek-oss/vanilla-extract/tree/master/packages/sprinkles), our official zero-runtime atomic CSS framework, built on top of vanilla-extract.
+Want to work at a higher level while maximising style re-use? Check out  🍨 [Sprinkles](https://vanilla-extract.style/documentation/sprinkles-api), our official zero-runtime atomic CSS framework, built on top of vanilla-extract.
 
 ---
 
@@ -1016,26 +1016,26 @@ document.write(`
 
 Your recipe configuration can also make use of existing variables, classes and styles.
 
-For example, you can use your `atoms` function from [Sprinkles.](https://github.com/seek-oss/vanilla-extract/tree/master/packages/sprinkles)
+For example, you can pass in the result of your [`sprinkles`](https://vanilla-extract.style/documentation/sprinkles-api) function directly.
 
 ```ts
 import { recipe } from '@vanilla-extract/recipes';
 import { reset } from './reset.css.ts';
-import { atoms } from './sprinkles.css.ts';
+import { sprinkles } from './sprinkles.css.ts';
 
 export const button = recipe({
-  base: [reset, atoms({ borderRadius: 'round' })],
+  base: [reset, sprinkles({ borderRadius: 'round' })],
 
   variants: {
     color: {
-      neutral: atoms({ background: 'neutral' }),
-      brand: atoms({ background: 'brand' }),
-      accent: atoms({ background: 'accent' })
+      neutral: sprinkles({ background: 'neutral' }),
+      brand: sprinkles({ background: 'brand' }),
+      accent: sprinkles({ background: 'accent' })
     },
     size: {
-      small: atoms({ padding: 'small' }),
-      medium: atoms({ padding: 'medium' }),
-      large: atoms({ padding: 'large' })
+      small: sprinkles({ padding: 'small' }),
+      medium: sprinkles({ padding: 'medium' }),
+      large: sprinkles({ padding: 'large' })
     }
   },
 

examples/webpack-react/src/App.css.ts

@@ -1,8 +1,8 @@
-import { style, composeStyles } from '@vanilla-extract/css';
-import { atoms } from './sprinkles.css';
+import { style } from '@vanilla-extract/css';
+import { sprinkles } from './sprinkles.css';
 
-export const card = composeStyles(
-  atoms({
+export const card = style([
+  sprinkles({
     background: {
       lightMode: 'green-50',
       darkMode: 'gray-800',
@@ -16,11 +16,11 @@ export const card = composeStyles(
       desktop: '8x',
     },
   }),
-  style({
+  {
     transition: 'transform 4s ease-in-out',
     ':hover': {
       cursor: 'default',
       transform: 'scale(2) rotate(720deg)',
     },
-  }),
-);
+  },
+]);

examples/webpack-react/src/App.tsx

@@ -1,9 +1,9 @@
-import { atoms } from './sprinkles.css';
+import { sprinkles } from './sprinkles.css';
 import * as styles from './App.css';
 
 export const App = () => (
   <div
-    className={atoms({
+    className={sprinkles({
       background: {
         lightMode: 'green-500',
         darkMode: 'gray-900',
@@ -17,7 +17,7 @@ export const App = () => (
   >
     <div className={styles.card}>
       <div
-        className={atoms({
+        className={sprinkles({
           display: 'flex',
           alignItems: 'center',
           flexDirection: 'column',
@@ -28,7 +28,7 @@ export const App = () => (
         })}
       >
         <h1
-          className={atoms({
+          className={sprinkles({
             fontFamily: 'body',
             textAlign: 'center',
             typeSize: {
@@ -49,7 +49,7 @@ export const App = () => (
           </span>
         </h1>
         <h2
-          className={atoms({
+          className={sprinkles({
             fontFamily: 'body',
             color: {
               lightMode: 'green-700',

examples/webpack-react/src/sprinkles.css.ts

@@ -1,7 +1,7 @@
-import { createAtomicStyles, createAtomsFn } from '@vanilla-extract/sprinkles';
+import { defineProperties, createSprinkles } from '@vanilla-extract/sprinkles';
 import { vars } from './vars.css';
 
-const responsiveStyles = createAtomicStyles({
+const responsiveProperties = defineProperties({
   conditions: {
     mobile: {},
     tablet: { '@media': 'screen and (min-width: 768px)' },
@@ -35,7 +35,7 @@ const responsiveStyles = createAtomicStyles({
   },
 });
 
-const colorModeStyles = createAtomicStyles({
+const colorModeProperties = defineProperties({
   conditions: {
     lightMode: {},
     darkMode: { '@media': '(prefers-color-scheme: dark)' },
@@ -47,4 +47,7 @@ const colorModeStyles = createAtomicStyles({
   },
 });
 
-export const atoms = createAtomsFn(responsiveStyles, colorModeStyles);
+export const sprinkles = createSprinkles(
+  responsiveProperties,
+  colorModeProperties,
+);

fixtures/sprinkles/src/index.ts

@@ -1,15 +1,15 @@
 import {
-  atoms,
+  sprinkles,
   mapResponsiveValue,
   normalizeResponsiveValue,
-  preComposedAtoms,
-  preComposedAtomsUsedInSelector,
+  preComposedSprinkles,
+  preComposedSprinklesUsedInSelector,
 } from './styles.css';
 import testNodes from '../test-nodes.json';
 
 function render() {
   document.body.innerHTML = `
-  <div id="${testNodes.root}" class="${atoms({
+  <div id="${testNodes.root}" class="${sprinkles({
     display: normalizeResponsiveValue('block').mobile,
     paddingTop: mapResponsiveValue(
       {
@@ -21,8 +21,8 @@ function render() {
   })}"> 
     Sprinkles
   </div>
-  <div class="${preComposedAtoms}">Precomposed atoms</div>
-  <div class="${preComposedAtomsUsedInSelector}">Precomposed Atoms Used In Selector</div>
+  <div class="${preComposedSprinkles}">Precomposed sprinkles</div>
+  <div class="${preComposedSprinklesUsedInSelector}">Precomposed Sprinkles Used In Selector</div>
 `;
 }
 

fixtures/sprinkles/src/styles.css.ts

@@ -1,15 +1,15 @@
 import { globalStyle, createVar } from '@vanilla-extract/css';
 import {
-  createAtomicStyles,
-  createAtomsFn,
+  defineProperties,
+  createSprinkles,
   createMapValueFn,
   createNormalizeValueFn,
 } from '@vanilla-extract/sprinkles';
 
 const alpha = createVar();
 const textAlpha = createVar();
 
-const responsiveStyles = createAtomicStyles({
+const responsiveProperties = defineProperties({
   defaultCondition: 'mobile',
   conditions: {
     mobile: {},
@@ -47,7 +47,7 @@ const responsiveStyles = createAtomicStyles({
   },
 });
 
-const styleWithNoConditions = createAtomicStyles({
+const unconditionalProperties = defineProperties({
   properties: {
     color: {
       red: {
@@ -64,13 +64,16 @@ const styleWithNoConditions = createAtomicStyles({
   },
 });
 
-export const atoms = createAtomsFn(responsiveStyles, styleWithNoConditions);
+export const sprinkles = createSprinkles(
+  responsiveProperties,
+  unconditionalProperties,
+);
 
-export const mapResponsiveValue = createMapValueFn(responsiveStyles);
+export const mapResponsiveValue = createMapValueFn(responsiveProperties);
 export const normalizeResponsiveValue =
-  createNormalizeValueFn(responsiveStyles);
+  createNormalizeValueFn(responsiveProperties);
 
-export const preComposedAtoms = atoms({
+export const preComposedSprinkles = sprinkles({
   display: 'block',
   paddingTop: 'small',
   background: 'red',
@@ -79,11 +82,11 @@ export const preComposedAtoms = atoms({
   textOpacity: 0.8,
 });
 
-export const preComposedAtomsUsedInSelector = atoms({
+export const preComposedSprinklesUsedInSelector = sprinkles({
   display: 'flex',
   paddingTop: 'medium',
 });
 
-globalStyle(`body > ${preComposedAtomsUsedInSelector}`, {
+globalStyle(`body > ${preComposedSprinklesUsedInSelector}`, {
   background: 'red',
 });