csstools / stylelint-value-no-unknown-custom-properties Goto Github PK

View Code? Open in Web Editor NEW

63.0 9.0 26.0 465 KB

A stylelint rule to catch usage of unknown custom properties

License: Creative Commons Zero v1.0 Universal

JavaScript 98.90% CSS 1.10%

stylelint-value-no-unknown-custom-properties's Introduction

Stylelint Value No Unknown Custom Properties

Stylelint Value No Unknown Custom Properties is a stylelint rule to disallow usage of unknown custom properties.

Usage

Add stylelint and Stylelint Value No Unknown Custom Properties to your project.

npm install stylelint stylelint-value-no-unknown-custom-properties --save-dev

Add Stylelint Value No Unknown Custom Properties to your stylelint configuration.

{
  "plugins": [
    "stylelint-value-no-unknown-custom-properties"
  ],
  "rules": {
    "csstools/value-no-unknown-custom-properties": true || null
  }
}

Options

true

If the first option is true, then Stylelint Value No Unknown Custom Properties requires all custom properties to be known, and the following patterns are not considered violations:

:root {
  --brand-blue: #33f;
}

.example {
  color: var(--brand-blue);
}

.example {
  color: var(--brand-blue);
}

.some-other-class {
  --brand-blue: #33f;
}

:root {
  --brand-blue: #33f;
  --brand-color: var(--brand-blue);
}

While the following patterns are considered violations:

.example {
  color: var(--brand-blue);
}

:root {
  --brand-color: var(--brand-blue);
}

Custom Properties can be imported using the second option.

`null`

If the first option is null, then Stylelint Value No Unknown Custom Properties does nothing.

importFrom

When the first option is true, then the second option can specify sources where Custom Properties should be imported from by using an importFrom key. These imports might be CSS, JS, and JSON files, functions, and directly passed objects.

The plugin resolves relative paths from the current working directory which may not work in monorepos, in which case it is best to pass only absolute paths to the plugin.

// .stylelintrc
{
  "plugins": [
    "stylelint-value-no-unknown-custom-properties"
  ],
  "rules": {
    "csstools/value-no-unknown-custom-properties": [true, {
      "importFrom": [
        "path/to/file.css", // => :root { --brand-blue: #33f; }
        "path/to/file.json" // => { "custom-properties": { "--brand-blue": "#33f" } }
      ]
    }]
  }
}

resolver

Use this option to configure how the rule solve paths of @import rules.

// .stylelintrc
{
  "plugins": [
    "stylelint-value-no-unknown-custom-properties"
  ],
  "rules": {
    "csstools/value-no-unknown-custom-properties": [true, {
      "resolver": {
        "extensions": [".css"], // => default to [".css"]
        "paths": ["./assets/css", "./static/css"], // => paths to look for files, default to []
        "moduleDirectories": ["node_modules"] // => modules folder to look for files, default to ["node_modules"]
      }
    }]
  }
}

stylelint-value-no-unknown-custom-properties's People

Contributors

Stargazers

Watchers

stylelint-value-no-unknown-custom-properties's Issues

importFrom HTML

I use a pattern where CSS vars are declared in a <style> tag in HTML to ensure they are available in all imported CSS files. Would be nice if this plugin could offer a way to read the vars from HTML:

<html>
  <head>
    <style>
      :root {
        --color-red: #dd2222;
      }
    </style>
  </head>
<html>

New release?

I can not see any release after this merge: #9. Is there any issue with that?

Does't work with `declaration-value`

When we have declaration-value in var function it return false-positive result

Example:

color: var(--my-undefined-color, #ffffff);

Support for import notation "url"

Hi!

It would be great if this package can have a support for import-notation: "url" !
Currently it cannot properly parse the following import notation

@import url("foo.css");

even though the URL notation is the default configuration in stylelint-config-standard.
ref: https://github.com/stylelint/stylelint-config-standard/blob/59f350d74df3665f50c19cd73b725d301b742413/index.js#L68C3-L68C3

Thanks a lot!

Consider adding rule to Stylelint

Thoughts / opinions on whether this rule should be graduated to a built-in Stylelint rule? I've been thinking about this since I found this rule after observing GitLab's interest in using it. I'm not sure if Stylelint would accept the rule into their built-in rules, as this rule is on the larger side when comparing with their other rules, but I think it's worth reaching out to them to get their thoughts. I've listed some grouped thoughts below.

If anything, this issue can also be seen as a list of potential improvements to the rule 🙂

Reasons for adding rule to Stylelint

CSS Tools maintainers can focus on postcss-plugins & cssdb.
Package has ~9,382 average weekly downloads. This is one of the top Stylelint community plugins / rules.
As a built-in rule, value-no-unknown-custom-properties (value-no-unknown-custom-property?) will (1) reach a larger audience, (2) gain regular maintenance along with other built-in rules, (3) take advantage of some of the built-in rules' shared utilities, (4) potentially gain performance / consistency improvements with rule being consistently tested in their CI, and (5) potentially gain more support for custom syntaxes which use custom properties.

Drawbacks for adding rule to Stylelint

Stylelint has not moved to ESM yet. Since this package has already moved to ESM, users of the library might not like the experience switching to the built-in rule. This may not be a problem if they are already using the built-in rules, though.

Action items before rule is ready to be added

Items are non-exhaustive, and open to changes requested. They are items I can initially find which makes this codebase closer to a built-in rule.

Format codebase using @stylelint/prettier-config.
Lint codebase using eslint-config-stylelint.
Lint JS types using TypeScript.
Remove Rollup in favor of no bundler.
Migrate from ESM to CommonJS module system.
Move around JS files to similar architecture of Stylelint rules.
Bring most of the files (rule name, messages, etc.) back into index.js.

importFrom function

In my codebase, we have multiple vars files and not all of them are imported in every consuming file.

I'd like to request that the importFrom supports a function so that the @imports can be resolved to provide the appropriate variables per file.

Scss string interpolation as custom property default #4999

Clearly describe the bug

Using an SCSS string interpolation for a custom property var() function default produce a CSSSyntaxError.

Which rule, if any, is the bug related to?

csstools/value-no-unknown-custom-properties

What code is needed to reproduce the bug?

$color: #fff;

.test {
  color: var(--color, #{$color});
}

What stylelint configuration is needed to reproduce the bug?

e.g.

{
  "plugins": ["stylelint-value-no-unknown-custom-properties"],
  "rules": {
    "csstools/value-no-unknown-custom-properties": [
      true,
      {
        "importFrom": "src/styles/global/variables.css"
      }
    ]
  }
}

Which version of stylelint are you using?

13.7.2

How are you running stylelint: CLI, PostCSS plugin, Node.js API?

CLI with stylelint --syntax scss 'src/**/*.scss'

Does the bug relate to non-standard syntax (e.g. SCSS, Less etc.)?

Yes, it's related to SCSS string interpolation.

What did you expect to happen?

No error.

What actually happened (e.g. what warnings or errors did you get)?

The following error were flagged:

$ stylelint --syntax scss 'src/**/*.scss'

<input css 1>
 1:11  ✖  Unknown word   CssSyntaxError

Support asterisk in importFrom

If **/*.css added to importFrom, we get following error:

Full path works but have to be changed per project. Can asterisk be supported to enable stylelint-value-no-unknown-custom-properties from all subdirectories or their subdirectories recursively?

ESM support

Please, add ESM support to be able to migrate to Stylelint 16 https://stylelint.io/migration-guide/to-16/

Resolve `importFrom` relative to config file, not working directory

In a monorepo with a .stylelintrc.yaml in a subdirectory I'm getting errors from my editor integration because this plugin resolves files relative to working directory instead of relative to the config file. I'd suggest to always resolve paths relative to the config file. This is how pretty much all other linters work too.

In case this suggestion is not possible, you could introduce a <rootDir> option like jest also has, e.g. <rootDir>/style.css to specify the path relative to the config file.

Angular compatibility

In angular projects, there is an angular.json file, where we can define a list of style sheets to import in the app (see https://angular.io/guide/workspace-config#additional-build-and-test-options). Then, the css variables defined in these root sheets don't necessary need to be imported via @import to be available in others css files.

In the pluggin, with the configuration property importFrom: ["/my-css.css"], the declared file seems to be used only when @import my-css.css is present in the file where the variable is used. So all the usages of my variables are in error, when they shouldn't, as they are declared in a root file.

Is there a way to add a new stylelint configuration property of style file paths, as importFrom one, used by the pluggin to search for variable declarations even if there is no @import statement in the file containing the variable usages?

Examples:
my-root-style.css

:root {
  --green: green;
}

my-other-style.css

body {
  color: var(--green);
}

This should be valid with a stylelint config file containing :

 rules: {
    "csstools/value-no-unknown-custom-properties": [
      true,
      {
        injectFrom: ["/my-root-style.scss"],
      },
    ],
  },

And this should still be invalid with a stylelint config file containing :

 rules: {
    "csstools/value-no-unknown-custom-properties": [
      true,
      {
        importFrom: ["/my-root-style.scss"],
      },
    ],
  },

 rules: {
    "csstools/value-no-unknown-custom-properties": [
      true
    ],
  },

Support for "importFrom" .less and .scss files

Hi!
Would be possible to add support for styles from .less & .scss files?

We directly use .less styles, but for Theme support, we decided to use css var(--xxx).

For now it is not blocker to use theme.css for us, because we have every "var" style in only one file (without any less things), but in the future?

Thanks!

Project status?

Just wondering if maintainers could give an update on this project's status - it looks like it has been shelved, but it's always better to hear from the actual maintainers than just guess. No anger or judgement intended, it would just be good to know for sure.

(also I don't really just mean "oi is this dead" I mean it's a great time to let us know if there's something the community can do, or some factor we don't know about that's blocking things)

Stylelint v15

Hi,
Would be possible to add support for stylelint v15+ ?

Thank you!

Publish v3.0.0 to npm

Thanks for the amazing library ❤️

I noticed you recently bumped the version to 3.0.0. Are there any plans on publishing this new version to npm?

I'm particular interested in the peedDependency change.

Cheers!

feature request: add option to allow unkown with fallback

In some cases I'd want to allow unknown properties if a fallback value would be present. Something like this:

color: var(--color-blue, blue);

Here --color-blue is unkown but it's okay since I have a fallback blue.

This may get tricky as fallbacks themselves could be var() with unkown values, but I'd like to know if you'd be open for this?

Suggestion for an other kind of processing

Instead of using importFrom or resolvers, use always the rendered css-variables from :root {} or a component (div, .custom1, #custom2, ...), based on the directory structure.

This would make it possible to use scss and allow theming.

Theme example:

/base.css
:root {
  --global-var: red;
}

/theme1/theme1.scss
:root {
  --theme1-var: green;
}

/theme2/theme2.scss
:root {
  --theme2-var: blue;
}

Usage:

/some-file.scss
body {
  background: var(--global-var); // ok
  background: var(--theme1-var); // error cause file is above dir /theme1
  background: var(--theme2-var); // error cause file is above dir /theme2
}

/theme1/some-file.scss
body {
  background: var(--global-var); // ok
  background: var(--theme1-var); // ok
  background: var(--theme2-var); // error cause file is outside of theme2
}

/theme2/some-file.scss
body {
  background: var(--global-var); // ok
  background: var(--theme1-var); // error cause file is outside of theme1
  background: var(--theme2-var); // ok
}

Or is such thing currently possible too?

Imports aren't relative (doesn't work with WebStorm)

You're using path.resolve() to find files, which defaults to using the current working directory.

I guess with WebStorm, which has Stylelint support built in, the 'current working directory' is the CSS file.

So when I define the path src\styles\colors.css for this rule, and view a file in the directory src\components\Button, I get the error:

Error: ENOENT: no such file or directory, open '...my-app\src\components\Button\src\styles\colors.css

Not exactly a fault of your plugin, so happy for you to close this (although if you wanted to be awesome, this plugin would treat paths as being relative to the config file).

The workaround (for future travellers) is to use a JS module for stylelint config and make sure that the paths passed to this plugin are absolute.

// stylelint.config.js
const path = require('path');

module.exports = {
  plugins: ['stylelint-value-no-unknown-custom-properties'],
  rules: {
    'csstools/value-no-unknown-custom-properties': [
      true,
      {
        importFrom: [
          path.resolve(__dirname, 'src/file1.css'),
          path.resolve(__dirname, 'src/file2.css'),
        ],
      },
    ],
  },
};