Skip to content

Commit 6ebf57e

Browse files
nzakasmdjermanovic
nzakas
and
mdjermanovic
authored
feat: Add use-layers rule (#27)
* feat: Add use-layers rule * Update README * @import should require layers by default * Fix types error * use-layers should not be recommended * Upgrade CSSTree to fix layer location error * Add valid test * Update src/rules/use-layers.js Co-authored-by: Milos Djermanovic <[email protected]> * Update docs/rules/use-layers.md Co-authored-by: Milos Djermanovic <[email protected]> * Update src/rules/use-layers.js Co-authored-by: Milos Djermanovic <[email protected]> --------- Co-authored-by: Milos Djermanovic <[email protected]>
1 parent 222b17a commit 6ebf57e

File tree

6 files changed

+526
-1
lines changed

6 files changed

+526
-1
lines changed

‎README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@ export default [
6262
| [`no-empty-blocks`](./docs/rules/no-empty-blocks.md) | Disallow empty blocks | yes |
6363
| [`no-invalid-at-rules`](./docs/rules/no-invalid-at-rules.md) | Disallow invalid at-rules | yes |
6464
| [`no-invalid-properties`](./docs/rules/no-invalid-properties.md) | Disallow invalid properties | yes |
65+
| [`use-layers`](./docs/rules/use-layers.md) | Require use of layers | no |
6566

6667
<!-- Rule Table End -->
6768

‎docs/rules/use-layers.md

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# use-layers
2+
3+
Require use of layers.
4+
5+
## Background
6+
7+
Layers are a way to organize the cascading of rules outside of their source code order. By defining named layers and describing their order, you can ensure that rules are applied in the order that best matches your use case. Here's an example:
8+
9+
```css
10+
/* establish the cascade order */
11+
@layer reset, base, theme;
12+
13+
/* import styles into the reset layer */
14+
@import url("reset.css") layer(reset);
15+
16+
/* Theme styles */
17+
@layer theme {
18+
body {
19+
background-color: #f0f0f0;
20+
color: #333;
21+
}
22+
}
23+
24+
/* Base styles */
25+
@layer base {
26+
body {
27+
font-family: Arial, sans-serif;
28+
line-height: 1.6;
29+
}
30+
}
31+
```
32+
33+
In general, you don't want to mix rules inside of layers with rules outside of layers because you're then dealing with two different cascade behaviors.
34+
35+
## Rule Details
36+
37+
This rule enforces the use of layers and warns when:
38+
39+
1. Any rule appears outside of a `@layer` block.
40+
1. Any `@import` doesn't specify a layer.
41+
1. If any layer doesn't have a name.
42+
43+
Examples of incorrect code:
44+
45+
```css
46+
/* no layer name */
47+
@import url(foo.css) layer;
48+
49+
/* no layer */
50+
@import url(bar.css);
51+
52+
/* outside of layer */
53+
.my-style {
54+
color: red;
55+
}
56+
57+
/* no layer name */
58+
@layer {
59+
a {
60+
color: red;
61+
}
62+
}
63+
```
64+
65+
There are also additional options to customize the behavior of this rule.
66+
67+
### Options
68+
69+
This rule accepts an options object with the following properties:
70+
71+
- `allowUnnamedLayers` (default: `false`) - Set to `true` to allow layers without names.
72+
- `layerNamePattern` (default: `""`) - Set to a regular expression string to validate all layer names.
73+
- `requireImportLayers` (default: `true`) - Set to `false` to allow `@import` rules without a layer.
74+
75+
#### `allowUnnamedLayers: true`
76+
77+
When `allowUnnamedLayers` is set to `true`, the following code is **correct**:
78+
79+
```css
80+
/* eslint css/use-layers: ["error", { allowUnnamedLayers: true }] */
81+
/* no layer name */
82+
@import url(foo.css) layer;
83+
84+
/* no layer name */
85+
@layer {
86+
a {
87+
color: red;
88+
}
89+
}
90+
```
91+
92+
#### `layerNamePattern`
93+
94+
The `layerNamePattern` is a regular expression string that allows you to validate the name of layers and prevent misspellings.
95+
96+
Here's an example of **incorrect** code:
97+
98+
```css
99+
/* eslint css/use-layers: ["error", { layerNamePattern: "^(reset|theme|base)$" }] */
100+
/* possible typo */
101+
@import url(foo.css) layer(resett);
102+
103+
/* unknown layer name */
104+
@layer defaults {
105+
a {
106+
color: red;
107+
}
108+
}
109+
```
110+
111+
#### `requireImportLayers: false`
112+
113+
When `requireImportLayers` is set to `false`, the following code is **correct**:
114+
115+
```css
116+
/* eslint css/use-layers: ["error", { requireImportLayers: false }] */
117+
@import url(foo.css);
118+
@import url(foo.css) layer;
119+
@import url(bar.css) layer(reset);
120+
```
121+
122+
## When Not to Use It
123+
124+
If you are defining rules without layers in a file (for example, `reset.css`) and then importing that file into a layer in another file (such as, `@import url(reset.css) layer(reset)`), then you should disable this rule in the imported file (in this example, `reset.css`). This rule is only needed in the file(s) that require layers.

‎package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@
7070
"license": "Apache-2.0",
7171
"dependencies": {
7272
"@eslint/plugin-kit": "^0.2.3",
73-
"css-tree": "^3.0.1"
73+
"css-tree": "^3.1.0"
7474
},
7575
"devDependencies": {
7676
"@eslint/core": "^0.7.0",

‎src/index.js

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ import noEmptyBlocks from "./rules/no-empty-blocks.js";
1313
import noDuplicateImports from "./rules/no-duplicate-imports.js";
1414
import noInvalidProperties from "./rules/no-invalid-properties.js";
1515
import noInvalidAtRules from "./rules/no-invalid-at-rules.js";
16+
import useLayers from "./rules/use-layers.js";
1617

1718
//-----------------------------------------------------------------------------
1819
// Plugin
@@ -31,6 +32,7 @@ const plugin = {
3132
"no-duplicate-imports": noDuplicateImports,
3233
"no-invalid-at-rules": noInvalidAtRules,
3334
"no-invalid-properties": noInvalidProperties,
35+
"use-layers": useLayers,
3436
},
3537
configs: {
3638
recommended: {

‎src/rules/use-layers.js

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
/**
2+
* @fileoverview Rule to require layers in CSS.
3+
* @author Nicholas C. Zakas
4+
*/
5+
6+
//-----------------------------------------------------------------------------
7+
// Rule Definition
8+
//-----------------------------------------------------------------------------
9+
10+
export default {
11+
meta: {
12+
type: /** @type {const} */ ("problem"),
13+
14+
docs: {
15+
description: "Require use of layers",
16+
url: "https://github.com/eslint/css/blob/main/docs/rules/use-layers.md",
17+
},
18+
19+
schema: [
20+
{
21+
type: "object",
22+
properties: {
23+
allowUnnamedLayers: {
24+
type: "boolean",
25+
},
26+
requireImportLayers: {
27+
type: "boolean",
28+
},
29+
layerNamePattern: {
30+
type: "string",
31+
},
32+
},
33+
additionalProperties: false,
34+
},
35+
],
36+
37+
defaultOptions: [
38+
{
39+
allowUnnamedLayers: false,
40+
requireImportLayers: true,
41+
layerNamePattern: "",
42+
},
43+
],
44+
45+
messages: {
46+
missingLayer: "Expected rule to be within a layer.",
47+
missingLayerName: "Expected layer to have a name.",
48+
missingImportLayer: "Expected import to be within a layer.",
49+
layerNameMismatch:
50+
"Expected layer name '{{ name }}' to match pattern '{{pattern}}'.",
51+
},
52+
},
53+
54+
create(context) {
55+
let layerDepth = 0;
56+
const options = context.options[0];
57+
const layerNameRegex = options.layerNamePattern
58+
? new RegExp(options.layerNamePattern, "u")
59+
: null;
60+
61+
return {
62+
"Atrule[name=import]"(node) {
63+
// layer, if present, must always be the second child of the prelude
64+
const secondChild = node.prelude.children[1];
65+
const layerNode =
66+
secondChild?.name === "layer" ? secondChild : null;
67+
68+
if (options.requireImportLayers && !layerNode) {
69+
context.report({
70+
loc: node.loc,
71+
messageId: "missingImportLayer",
72+
});
73+
}
74+
75+
if (layerNode) {
76+
const isLayerFunction = layerNode.type === "Function";
77+
78+
if (!options.allowUnnamedLayers && !isLayerFunction) {
79+
context.report({
80+
loc: layerNode.loc,
81+
messageId: "missingLayerName",
82+
});
83+
}
84+
}
85+
},
86+
87+
Layer(node) {
88+
if (!layerNameRegex) {
89+
return;
90+
}
91+
92+
if (!layerNameRegex.test(node.name)) {
93+
context.report({
94+
loc: node.loc,
95+
messageId: "layerNameMismatch",
96+
data: {
97+
name: node.name,
98+
pattern: options.layerNamePattern,
99+
},
100+
});
101+
}
102+
},
103+
104+
"Atrule[name=layer]"(node) {
105+
layerDepth++;
106+
107+
if (!options.allowUnnamedLayers && !node.prelude) {
108+
context.report({
109+
loc: node.loc,
110+
messageId: "missingLayerName",
111+
});
112+
}
113+
},
114+
115+
"Atrule[name=layer]:exit"() {
116+
layerDepth--;
117+
},
118+
119+
Rule(node) {
120+
if (layerDepth > 0) {
121+
return;
122+
}
123+
124+
context.report({
125+
loc: node.loc,
126+
messageId: "missingLayer",
127+
});
128+
},
129+
};
130+
},
131+
};

0 commit comments

Comments
 (0)