add support for css @property

[z4o4z]

This PR adds support for CSS @property feature.

• createVar - creates a @property definition, returns property var format var(--propertyName)
• createGlobalVar - same as createVar but with a predefined name
• getVarName - accepts a property var format and returns just a property name var(--propertyName) -> --propertyName

example:

import { style, createVar, keyframes, getVarName, fallbackVar } from '@vanilla-extract/css';

const color = createVar();
const angle = createVar({
  syntax: '<angle>',
  inherits: false,
  initialValue: '0deg',
});

const angleKeyframes = keyframes({
  '100%': {
    [getVarName(angle)]: '360deg',
  },
});

export const root = style({
  background: 'pink',
  color: 'blue',
  padding: '16px',
  transition: `opacity .1s ease, color .1s ease`, // Testing autoprefixer
  backgroundImage: `linear-gradient(${angle}, rgba(153, 70, 198, 0.35) 0%, rgba(28, 56, 240, 0.46) 100%)`,
  animation: `${angleKeyframes} 7s infinite ease-in-out both`,


  ':hover': {
    opacity: 0.8,
    color: color,
  },
  
  vars: {
    [color]: '#fef',
    [angle]: fallbackVar(angle, '138deg'),
  }
});

[changeset-bot]

🦋 Changeset detected

Latest commit: 53ec657

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 28 packages

Name	Type
@vanilla-extract/babel-plugin-debug-ids	Minor
@vanilla-extract/css	Minor
@vanilla-extract/integration	Patch
@vanilla-extract/rollup-plugin	Patch
@fixtures/features	Patch
@fixtures/layers	Patch
@fixtures/low-level	Patch
@fixtures/next-app-router	Patch
@fixtures/next-pages-router	Patch
@fixtures/recipes	Patch
@fixtures/sprinkles	Patch
@fixtures/template-string-paths	Patch
@fixtures/themed	Patch
@fixtures/thirdparty	Patch
@fixtures/unused-modules	Patch
@fixtures/thirdparty-dep	Patch
@fixtures/thirdparty-dep-dep	Patch
vanilla-extract-example-remix	Patch
vanilla-extract-example-webpack-react	Patch
@vanilla-extract-private/tests	Patch
@vanilla-extract/esbuild-plugin-next	Patch
@vanilla-extract/esbuild-plugin	Patch
@vanilla-extract/jest-transform	Patch
@vanilla-extract/parcel-transformer	Patch
@vanilla-extract/vite-plugin	Patch
@vanilla-extract/webpack-plugin	Patch
@vanilla-extract-private/test-helpers	Patch
@vanilla-extract/next-plugin	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[markdalgleish]

Thanks for the PR! This looks really great.

To me this is just an extension of our current createVar API. The fact that it's natively called @property definitely challenges our current naming, but I think for now VE needs to be consistent in calling them "vars". If we rename them to properties, we'd do this across the whole library in a future major version. I think it's okay that internals refer to it as "property" though since this future-proofs the integration package against API changes.

So I think we'd need to make the following changes for now:

• Overload createVar so the API is createVar({ syntax: '<color>', inherits: false, initialValue: '#fff' }).
• Rename createGlobalProperty to createGlobalVar.
• Replace getPropertyName with getVarName (which already exists in our private package). This would need to be exposed from css and dynamic packages since you'd want this at both build time and run time.

[z4o4z]

Thanks for the PR! This looks really great.

To me this is just an extension of our current createVar API. The fact that it's natively called @property definitely challenges our current naming, but I think for now VE needs to be consistent in calling them "vars". If we rename them to properties, we'd do this across the whole library in a future major version. I think it's okay that internals refer to it as "property" though since this future-proofs the integration package against API changes.

So I think we'd need to make the following changes for now:

• Overload createVar so the API is createVar({ syntax: '<color>', inherits: false, initialValue: '#fff' }).
• Rename createGlobalProperty to createGlobalVar.
• Replace getPropertyName with getVarName (which already exists in our private package). This would need to be exposed from css and dynamic packages since you'd want this at both build time and run time.

hey @markdalgleish, thanks for your feedback! Updated the code, pls let me know if I need to change something else

[z4o4z]

@markdalgleish thanks for cleaning this up! is there something I should address before merging?

[z4o4z]

@markdalgleish any updates here, i'm really waiting for this feature?

[erwinsmit]

@markdalgleish any updates here, i'm really waiting for this feature?

This would be a nice addition. Currently I can only use properties using globalStyle with a @ts-ignore. That feels a bit dirty

globalStyle(`@property --headerBackground1`, {
  // @ts-ignore
  syntax: `'<color>'`,
  initialValue: colorPrimitives.neutrals.whites.W100,
  inherits: false,
});

[8bit-echo]

I'd like to bump this and see it land! 🙏 This would be a great feature for our design system to use.

[mikaalnaik]

Need this as well, any update to this PRs future @markdalgleish?

[lukelarsen]

I am also needing this in our current library. Any update?

[askoufis]

Hey, I'm keen to help get this PR through the door. For me, there's a few things still missing.

Testing @property CSS output in a fixture

Your example in examples/next is somewhat complex, and isn't actually being tested anywhere. We snapshot screenshots and CSS output of each of the fixture packages, so maybe adding a simple property in the themed fixture would be enough.

Unit testing CSS output

This is done in transformCss.test.ts. You probably just need to add a single test case that uses an object with type: 'property'.

Docs

We tend to be a bit particular about docs, so that can be left to a separate PR. However, you're more than welcome try write them yourself if you want.

[askoufis]

@z4o4z Hey, are you still interested in getting this PR over the line? If not, I may look at picking it up myself in the near future.

[z4o4z]

hey @askoufis, i've added tests and updated docs. let me know if that looks good for you :) Thanks for helping with the PR!

[askoufis]

Thanks for picking this up again @z4o4z, it's most of the way there. For me the last missing bit is docs for createGlobalVar, which should be fairly straightforward. I've also made a comment about keyframes below.

Once the last bits are ready there's also some playwright snapshots that need updating.

[z4o4z]

@askoufis addressed the feedback + improved documentation. I found out that parcel doesn't support @property and all parcel-related playwright tests are failing now, not sure what to do with it...

[z4o4z]

@askoufis addressed the feedback + improved documentation. I found out that parcel doesn't support @property and all parcel-related playwright tests are failing now, not sure what to do with it...

looks like it's not the parcel issue itself, parcel uses lightningcss to build CSS, and lightningcss doesn't support @property keyword (playground) :(

Created the issue: parcel-bundler/lightningcss#820

hope it's not a blocker...

not a real issue

[z4o4z]

looks like it wasn't an issue in the parcel, apparently initial-value is required for non * syntax, so it was failing with not really useful error. So i've made initialValue required on type level for non * syntax.

Should be good to merge

[askoufis]

Thanks for the quick updates. Just some more minor comments from me.

Also realised there's no changesets for the features. We'll need one for createVar and createGlobalVar, as well as a separate one for adding vars support to keyframes. There's actually a few more changes that need changeesets. I'll add them.

[askoufis]

@markdalgleish Would you mind giving this another review when you've got some time?

[askoufis]

Looks like linting is also failing, specifically prettier.

[z4o4z]

@askoufis thanks for the feedback! addressed everything

[z4o4z]

hey @askoufis @markdalgleish any chance we can merge it soon?