Skip to content

Latest commit

 

History

History
762 lines (625 loc) · 9.82 KB

README.md

File metadata and controls

762 lines (625 loc) · 9.82 KB
Raw

order

Specify the order of content within declaration blocks.

Options

type PrimaryOption = Array<Keyword | AtRule | Rule>;

type Keyword = "custom-properties" | "dollar-variables" | "at-variables" | "declarations" | "rules" | "at-rules" | "less-mixins";

type AtRule = {
	type: 'at-rule';
	name?: string;
	parameter?: string | RegExp;
	hasBlock?: boolean;
};

type Rule = {
	type: 'rule';
	selector?: string | RegExp;
	name?: string;
};

Within an order array, you can include:

  • keywords:

    • custom-properties — Custom properties (e. g., --property: 10px;)
    • dollar-variables — Dollar variables (e. g., $variable)
    • at-variables — At-variables (e. g., @variable available in Less syntax)
    • declarations — CSS declarations (e. g., display: block)
    • rules — Nested rules (e. g., a { span {} })
    • at-rules — Nested at-rules (e. g., div { @media () {} })
    • less-mixins — Mixins in Less syntax (e. g., .mixin();)

  • extended at-rule objects:

     {
 	"type": "at-rule",
 	"name": "include",
 	"parameter": "hello",
 	"hasBlock": true
 }

  • extended rule objects:

     {
 	"type": "rule",
 	"selector": "div",
 	"name": "tag selector"
 }

By default, unlisted elements will be ignored. So if you specify an array and do not include declarations, that means that all declarations can be included before or after any other element. This can be changed with the unspecified option (see below).

Extended at-rule objects

Extended at-rule objects have different parameters and variations.

Object parameters:

  • type: always "at-rule"
  • name: string. E. g., name: "include" for @include
  • parameter: string | RegExp. A string will be translated into a RegExp — new RegExp(yourString) — so be sure to escape properly. E. g., parameter: "icon" for @include icon(20px);
  • hasBlock: boolean. E. g., hasBlock: true for @include icon { color: red; } and not for @include icon;

Always specify name if parameter is specified.

Matches all at-rules:

{
	"type": "at-rule"
}

Or keyword at-rules.

Matches all at-rules, which have nested elements:

{
	"type": "at-rule",
	"hasBlock": true
}

Matches all at-rules with specific name:

{
	"type": "at-rule",
	"name": "media"
}

Matches all at-rules with specific name, which have nested elements:

{
	"type": "at-rule",
	"name": "media",
	"hasBlock": true
}

Matches all at-rules with specific name and parameter:

{
	"type": "at-rule",
	"name": "include",
	"parameter": "icon"
}

Matches all at-rules with specific name and parameter, which have nested elements:

{
	"type": "at-rule",
	"name": "include",
	"parameter": "icon",
	"hasBlock": true
}

Each described above variant has more priority than its previous variant. For example, { "type": "at-rule", "name": "media" } will be applied to an element if both { "type": "at-rule", "name": "media" } and { "type": "at-rule", "hasBlock": true } can be applied to an element.

Extended rule objects

Object parameters:

  • type: always "rule"
  • selector: string | RegExp. Selector pattern. A string will be translated into a RegExp — new RegExp(yourString) — so be sure to escape properly. Examples:
    • selector: /^&:[\w-]+$/ matches simple pseudo-classes. E. g., &:hover, &:first-child. Doesn't match complex pseudo-classes, e. g. &:not(.is-visible).
    • selector: /^&::[\w-]+$/ matches pseudo-elements. E. g. &::before, &::placeholder.
  • name: string. Selector name (optional). Will be used in error output to help identify extended rule object.

Matches all rules:

{
	"type": "rule"
}

Or keyword rules.

Matches all rules with selector matching pattern:

{
	"type": "rule",
	"selector": "div"
}
{
	"type": "rule",
	"selector": "/^&:\\w+$/"
}

Optional secondary options

type SecondaryOptions = {
	unspecified?: "top" | "bottom" | "ignore";
};

unspecified

Value type: "top" | "bottom" | "ignore".
Default value: "ignore".

Default behavior is the same as "ignore": an unspecified element can appear before or after any other property.

With "top", unspecified elements are expected before any specified properties. With "bottom", unspecified properties are expected after any specified properties.

Autofixing caveats

Keyword less-mixins aren't supported.

unspecified secondary option is always set to bottom.

Examples

Given:

{
	"order/order": [
		"custom-properties",
		"dollar-variables",
		"declarations",
		"rules",
		"at-rules"
	]
}

The following patterns are considered warnings:

a {
	top: 0;
	--height: 10px;
	color: pink;
}
a {
	@media (min-width: 100px) {}
	display: none;
}

The following patterns are not considered warnings:

a {
	--width: 10px;
	$height: 20px;
	display: none;
	span {}
	@media (min-width: 100px) {}
}
a {
	--height: 10px;
	color: pink;
	top: 0;
}

Given:

{
	"order/order": [
		{
			"type": "at-rule",
			"name": "include"
		},
		{
			"type": "at-rule",
			"name": "include",
			"hasBlock": true
		},
		{
			"type": "at-rule",
			"hasBlock": true
		},
		{
			"type": "at-rule"
		}
	]
}

The following patterns are considered warnings:

a {
	@include hello {
		display: block;
	}
	@include hello;
}
a {
	@extend .something;
	@media (min-width: 10px) {
		display: none;
	}
}

The following patterns are not considered warnings:

a {
	@include hello;
	@include hello {
		display: block;
	}
	@media (min-width: 10px) {
		display: none;
	}
	@extend .something;
}
a {
	@include hello {
		display: block;
	}
	@extend .something;
}

Given:

{
	"order/order": [
		{
			"type": "at-rule",
			"name": "include",
			"hasBlock": true
		},
		{
			"type": "at-rule",
			"name": "include",
			"parameter": "icon",
			"hasBlock": true
		},
		{
			"type": "at-rule",
			"name": "include",
			"parameter": "icon"
		}
	]
}

The following patterns are considered warnings:

a {
	@include icon {
		display: block;
	}
	@include hello {
		display: none;
	}
	@include icon;
}
a {
	@include icon;
	@include icon {
		display: block;
	}
}

The following patterns are not considered warnings:

a {
	@include hello {
		display: none;
	}
	@include icon {
		display: block;
	}
	@include icon;
}
a {
	@include hello {
		display: none;
	}
	@include icon;
}

Given:

{
	"order/order": [
		"custom-properties",
		{
			"type": "at-rule",
			"hasBlock": true
		},
		"declarations"
	]
}

The following patterns are considered warnings:

a {
	@media (min-width: 10px) {
		display: none;
	}
	--height: 10px;
	width: 20px;
}
a {
	width: 20px;
	@media (min-width: 10px) {
		display: none;
	}
	--height: 10px;
}
a {
	width: 20px;
	@media (min-width: 10px) {
		display: none;
	}
}

The following patterns are not considered warnings:

a {
	--height: 10px;
	@media (min-width: 10px) {
		display: none;
	}
	width: 20px;
}
a {
	@media (min-width: 10px) {
		display: none;
	}
	width: 20px;
}
a {
	--height: 10px;
	width: 20px;
}

Given:

{
	"order/order": [
		{
			"type": "rule",
			"selector": "^a"
		},
		{
			"type": "rule",
			"selector": "/^&/"
		},
		"rules"
	]
}

The following patterns are considered warnings:

a {
	a {}
	&:hover {}
	abbr {}
	span {}
}
a {
	span {}
	&:hover {}
}
a {
	span {}
	abbr {}
}

The following patterns are not considered warnings:

a {
	a {}
	abbr {}
	&:hover {}
	span {}
}
a {
	abbr {}
	a {}
}
a {
	abbr {}
	span {}
}

Given:

{
	"order/order": [
		{
			"type": "rule",
			"selector": "/^&/"
		},
		{
			"type": "rule",
			"selector": "/^&:\\w/"
		}
	]
}

The following patterns are not considered warnings:

a {
	&:hover {}
	& b {}
}
a {
	& b {}
	&:hover {}
}

Given:

{
	"order/order": [
		{
			"type": "rule",
			"selector": "/^&:\\w/"
		},
		{
			"type": "rule",
			"selector": "/^&/"
		}
	]
}

The following pattern is considered warnings:

a {
	& b {}
	&:hover {}
}

The following pattern is not considered warnings:

a {
	&:hover {}
	& b {}
}

Given:

{
	"order/order": [
		[
			"declarations"
		],
		{
			"unspecified": "ignore"
		}
	]
}

The following patterns are not considered warnings:

a {
	--height: 10px;
	display: none;
	$width: 20px;
}
a {
	--height: 10px;
	$width: 20px;
	display: none;
}
a {
	display: none;
	--height: 10px;
	$width: 20px;
}

Given:

{
	"order/order": [
		[
			"declarations"
		],
		{
			"unspecified": "top"
		}
	]
}

The following patterns are considered warnings:

a {
	display: none;
	--height: 10px;
	$width: 20px;
}
a {
	--height: 10px;
	display: none;
	$width: 20px;
}

The following patterns are not considered warnings:

a {
	--height: 10px;
	$width: 20px;
	display: none;
}
a {
	$width: 20px;
	--height: 10px;
	display: none;
}

Given:

{
	"order/order": [
		[
			"declarations"
		],
		{
			"unspecified": "bottom"
		}
	]
}

The following patterns are considered warnings:

a {
	--height: 10px;
	$width: 20px;
	display: none;
}
a {
	--height: 10px;
	display: none;
	$width: 20px;
}

The following patterns are not considered warnings:

a {
	display: none;
	--height: 10px;
	$width: 20px;
}
a {
	display: none;
	$width: 20px;
	--height: 10px;
}