@projectwallace/format-css 0.1.0

package/.github/workflows/test.yml

@@ -0,0 +1,24 @@
+# This workflow will do a clean install of node dependencies, build the source code and run tests across different versions of node
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions
+
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Unit tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Use Node.js 18
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache: "npm"
+      - run: npm install --ignore-scripts --no-audit
+      - run: npm test

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Project Wallace
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# format-css
+
+Lightweight and fast library to format CSS with some very basic [rules](#formatting-rules). Our design goal is to format CSS in such a way that it's easy to inspect. Bundle size and runtime speed are more important than versatility and extensibility.
+
+![Example input-output of this formatter](https://github.com/projectwallace/format-css/assets/1536852/ce160fd3-fa11-4d90-9432-22567ee1d851)
+
+## Installation
+
+```
+npm install @projectwallace/format-css
+```
+
+## Usage
+
+```js
+import { format } from "@projectwallace/format-css";
+
+let old_css = "/* Your old CSS here */";
+let new_css = format(old_css);
+```
+
+## Formatting rules
+
+1. Every **AtRule** starts on a new line
+1. Every **Rule** starts on a new line
+1. Every **Selector** starts on a new line
+1. A comma is placed after every **Selector** that’s not the last in the **SelectorList**
+1. Every **Block** is indented with 1 tab more than the previous indentation level
+1. Every **Declaration** starts on a new line
+1. Every **Declaration** ends with a semicolon (;)
+1. An empty line is placed after a **Block**, unless it’s the last in the surrounding **Block**
+1. Unknown syntax is rendered as-is
+
+## Acknowledgements
+
+- Thanks to [CSSTree](https://github.com/csstree/csstree) for providing the necessary parser and the interfaces for our CSS Types (the **bold** elements in the list above)
+- Thanks to [Prettier](https://prettier.io) and countless others for prior art

package/index.js

@@ -0,0 +1,214 @@
+import parse from 'css-tree/parser'
+
+/**
+ * Indent a string
+ * @param {number} size
+ * @returns A string with {size} tabs
+ */
+function indent(size) {
+	return '\t'.repeat(size)
+}
+
+/**
+ * @param {import('css-tree').CssNode} node
+ * @param {string} css
+ * @returns A portion of the CSS
+ */
+function substr(node, css) {
+	if (node.loc) {
+		return css.substring(node.loc.start.offset, node.loc.end.offset)
+	}
+	return ''
+}
+
+/**
+ *
+ * @param {import('css-tree').Rule} node
+ * @param {number} indent_level
+ * @param {string} css
+ * @returns {string} A formatted Rule
+ */
+function print_rule(node, indent_level, css) {
+	let buffer = ''
+
+	if (node.prelude && node.prelude.type === 'SelectorList') {
+		buffer += print_selectorlist(node.prelude, indent_level, css)
+	}
+
+	if (node.block && node.block.type === 'Block') {
+		buffer += print_block(node.block, indent_level, css)
+	}
+
+	return buffer
+}
+
+/**
+ * @param {import('css-tree').SelectorList} node
+ * @param {number} indent_level
+ * @param {string} css
+ * @returns {string} A formatted SelectorList
+ */
+function print_selectorlist(node, indent_level, css) {
+	let buffer = ''
+
+	for (let selector of node.children) {
+		if (selector !== node.children.first) {
+			buffer += '\n'
+		}
+
+		if (selector.type === 'Selector') {
+			buffer += print_selector(selector, indent_level, css)
+		} else {
+			buffer += print_unknown(selector, indent_level, css)
+		}
+
+		if (selector !== node.children.last) {
+			buffer += ','
+		}
+	}
+	return buffer
+}
+
+/**
+ *
+ * @param {import('css-tree').Selector} node
+ * @param {number} indent_level
+ * @param {string} css
+ * @returns {string} A formatted Selector
+ */
+function print_selector(node, indent_level, css) {
+	return indent(indent_level) + substr(node, css)
+}
+
+/**
+ * @param {import('css-tree').Block} node
+ * @param {number} indent_level
+ * @param {string} css
+ * @returns {string} A formatted Block
+ */
+function print_block(node, indent_level, css) {
+	let children = node.children
+
+	if (children.size === 0) {
+		return ' {}\n'
+	}
+
+	let buffer = ' {\n'
+
+	indent_level++
+
+	for (let child of children) {
+		if (child.type === 'Declaration') {
+			buffer += print_declaration(child, indent_level, css)
+		} else if (child.type === 'Rule') {
+			buffer += print_rule(child, indent_level, css)
+		} else if (child.type === 'Atrule') {
+			buffer += print_atrule(child, indent_level, css)
+		} else {
+			buffer += print_unknown(child, indent_level, css)
+		}
+
+		if (child !== children.last) {
+			if (child.type === 'Declaration') {
+				buffer += '\n'
+			} else {
+				buffer += '\n\n'
+			}
+		}
+	}
+
+	indent_level--
+
+	buffer += '\n'
+	buffer += indent(indent_level)
+	buffer += '}'
+
+	return buffer
+}
+
+/**
+ * @param {import('css-tree').Atrule} node
+ * @param {number} indent_level
+ * @param {string} css
+ * @returns {string} A formatted Atrule
+ */
+function print_atrule(node, indent_level, css) {
+	let buffer = indent(indent_level)
+	buffer += '@' + node.name
+
+	// @font-face has no prelude
+	if (node.prelude) {
+		buffer += ' ' + substr(node.prelude, css)
+	}
+
+	if (node.block && node.block.type === 'Block') {
+		buffer += print_block(node.block, indent_level, css)
+	} else {
+		// `@import url(style.css);` has no block, neither does `@layer layer1;`
+		buffer += ';'
+	}
+
+	return buffer
+}
+
+/**
+ * @param {import('css-tree').Declation} node
+ * @param {number} indent_level
+ * @param {string} css
+ * @returns {string} A formatted Declaration
+ */
+function print_declaration(node, indent_level, css) {
+	return indent(indent_level) + node.property + ': ' + substr(node.value, css) + ';'
+}
+
+/**
+ * @param {import('css-tree').CssNode} node
+ * @param {number} indent_level
+ * @param {string} css
+ * @returns {string} A formatted unknown CSS string
+ */
+function print_unknown(node, indent_level, css) {
+	return indent(indent_level) + substr(node, css).trim()
+}
+
+/**
+ * @param {import('css-tree').Stylesheet} node
+ * @param {number} indent_level
+ * @param {string} css
+ * @returns {string} A formatted Stylesheet
+ */
+function print(node, indent_level = 0, css) {
+	let buffer = ''
+	let children = node.children
+
+	for (let child of children) {
+		if (child.type === 'Rule') {
+			buffer += print_rule(child, indent_level, css)
+		} else if (child.type === 'Atrule') {
+			buffer += print_atrule(child, indent_level, css)
+		} else {
+			buffer += print_unknown(child, indent_level, css)
+		}
+
+		if (child !== children.last) {
+			buffer += '\n\n'
+		}
+	}
+
+	return buffer
+}
+
+/**
+ * Take a string of CSS (minified or not) and format it with some simple rules
+ * @param {string} css The original CSS
+ * @returns {string} The newly formatted CSS
+ */
+export function format(css) {
+	let ast = parse(css, {
+		positions: true,
+		parseAtrulePrelude: false,
+		parseCustomProperty: false,
+		parseValue: false,
+	})
+	return print(ast, 0, css)
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@projectwallace/format-css",
+  "version": "0.1.0",
+  "type": "module",
+  "source": "index.js",
+  "exports": {
+    "require": "./dist/format.cjs",
+    "default": "./dist/format.modern.js"
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/format.cjs",
+  "module": "./dist/format.module.js",
+  "unpkg": "./dist/format.umd.js",
+  "scripts": {
+    "build": "microbundle",
+    "test": "uvu"
+  },
+  "devDependencies": {
+    "@types/css-tree": "^2.3.1",
+    "microbundle": "^0.15.1",
+    "uvu": "^0.5.6"
+  },
+  "dependencies": {
+    "css-tree": "^2.3.1"
+  }
+}

package/test.js

@@ -0,0 +1,373 @@
+import { test } from 'uvu'
+import * as assert from 'uvu/assert'
+import { format } from './index.js'
+
+test('AtRules and Rules start on a new line', () => {
+	let actual = format(`
+		selector { property: value; }
+		@media (min-width: 1000px) {
+			selector { property: value; }
+		}
+		selector { property: value; }
+		@layer test {
+			selector { property: value; }
+		}
+	`)
+	let expected = `selector {
+	property: value;
+}
+
+@media (min-width: 1000px) {
+	selector {
+		property: value;
+	}
+}
+
+selector {
+	property: value;
+}
+
+@layer test {
+	selector {
+		property: value;
+	}
+}`
+
+	assert.equal(actual, expected)
+})
+
+test('Atrule blocks are surrounded by {} with correct spacing and indentation', () => {
+	let actual = format(`
+		@media (min-width:1000px){selector{property:value}}
+
+		@media (min-width:1000px)
+		{
+			selector
+			{
+				property:value
+			}
+}`)
+	let expected = `@media (min-width:1000px) {
+	selector {
+		property: value;
+	}
+}
+
+@media (min-width:1000px) {
+	selector {
+		property: value;
+	}
+}`
+
+	assert.equal(actual, expected)
+})
+
+test('Does not do AtRule prelude formatting', () => {
+	let actual = format(`@media (min-width:1000px){}`)
+	let expected = `@media (min-width:1000px) {}
+`
+
+	assert.equal(actual, expected)
+})
+
+test('Selectors are placed on a new line, separated by commas', () => {
+	let actual = format(`
+		selector1,
+			selector1a,
+			selector1b,
+				selector1aa,
+		selector2,
+
+		selector3 {
+		}
+	`)
+	let expected = `selector1,
+selector1a,
+selector1b,
+selector1aa,
+selector2,
+selector3 {}
+`
+
+	assert.equal(actual, expected)
+})
+
+test('Declarations end with a semicolon (;)', () => {
+	let actual = format(`
+		@font-face {
+			src: url('test');
+			font-family: Test;
+		}
+
+		css {
+			property1: value2;
+			property2: value2;
+
+			& .nested {
+				property1: value2;
+				property2: value2
+			}
+		}
+
+		@media (min-width: 1000px) {
+			@layer test {
+				css {
+					property1: value1
+				}
+			}
+		}
+	`)
+	let expected = `@font-face {
+	src: url('test');
+	font-family: Test;
+}
+
+css {
+	property1: value2;
+	property2: value2;
+	& .nested {
+		property1: value2;
+		property2: value2;
+	}
+}
+
+@media (min-width: 1000px) {
+	@layer test {
+		css {
+			property1: value1;
+		}
+	}
+}`
+
+	assert.equal(actual, expected)
+})
+
+test('An empty line is rendered in between Rules', () => {
+	let actual = format(`
+		rule1 { property: value }
+		rule2 { property: value }
+	`)
+	let expected = `rule1 {
+	property: value;
+}
+
+rule2 {
+	property: value;
+}`
+	assert.equal(actual, expected)
+})
+
+test('single empty line after a rule, before atrule', () => {
+	let actual = format(`
+		rule1 { property: value }
+		@media (min-width: 1000px) {
+			rule2 { property: value }
+		}
+	`)
+	let expected = `rule1 {
+	property: value;
+}
+
+@media (min-width: 1000px) {
+	rule2 {
+		property: value;
+	}
+}`
+	assert.equal(actual, expected)
+})
+
+test('single empty line in between atrules', () => {
+	let actual = format(`
+		@layer test1;
+		@media (min-width: 1000px) {
+			rule2 { property: value }
+		}
+	`)
+	let expected = `@layer test1;
+
+@media (min-width: 1000px) {
+	rule2 {
+		property: value;
+	}
+}`
+	assert.equal(actual, expected)
+})
+
+test('handles comments', () => {
+	let actual = format(`
+.async-hide {
+	opacity: 0;
+}
+
+/*!
+ * Library vx.x.x (http://css-lib.com)
+ * Copyright 1970-1800 CSS Inc.
+ * Licensed under MIT (https://example.com)
+ */
+
+/*! normalize.css v3.0.3 | MIT License | github.com/necolas/normalize.css */
+
+html /* comment */ {
+	font-family /* comment */ : /* comment */ sans-serif;
+	-webkit-text-size-adjust: 100%;
+	-ms-text-size-adjust: 100%;
+}
+	`)
+	let expected = `.async-hide {
+	opacity: 0;
+}
+
+/*!
+ * Library vx.x.x (http://css-lib.com)
+ * Copyright 1970-1800 CSS Inc.
+ * Licensed under MIT (https://example.com)
+ */
+
+/*! normalize.css v3.0.3 | MIT License | github.com/necolas/normalize.css */
+
+html {
+	font-family: sans-serif;
+	-webkit-text-size-adjust: 100%;
+	-ms-text-size-adjust: 100%;
+}`
+
+	assert.equal(actual, expected)
+})
+
+test('css nesting chaos', () => {
+	let actual = format(`
+/**
+ * Comment!
+ */
+no-layer-1, no-layer-2 { color: red; font-size: 1rem; COLOR: green; }
+@layer components, deep;
+@layer base { layer-base { color: green; } }
+@layer { @layer named { anon-named { test: 1 } }}
+@media (min-width: 1000px) {
+  @layer desktop { layer-desktop { color: blue; } }
+  @layer { layer-anon, no-2 { anonymous: 1; } }
+  @layer test {}
+  @supports (min-width: 1px) {
+    @layer deep { layer-deep {} }
+  }
+}
+test { a: 1}
+@layer components {
+  @layer alert {}
+  @layer table {
+    @layer tbody, thead;
+    layer-components-table { color: yellow; }
+    @layer tbody { tbody { border: 1px solid; background: red; } }
+    @media (min-width: 30em) {
+      @supports (display: grid) {
+        @layer thead { thead { border: 1px solid; } }
+      }
+    }
+  }
+}
+@layer components.breadcrumb { layer-components-breadcrumb { } }
+
+@font-face {
+  font-family: "Test";
+  src: url(some-url.woff2);
+}
+
+;;;;;;;;;;;;;;;;;;;
+`)
+	let expected = `no-layer-1,
+no-layer-2 {
+	color: red;
+	font-size: 1rem;
+	COLOR: green;
+}
+
+@layer components, deep;
+
+@layer base {
+	layer-base {
+		color: green;
+	}
+}
+
+@layer {
+	@layer named {
+		anon-named {
+			test: 1;
+		}
+	}
+}
+
+@media (min-width: 1000px) {
+	@layer desktop {
+		layer-desktop {
+			color: blue;
+		}
+	}
+
+	@layer {
+		layer-anon,
+		no-2 {
+			anonymous: 1;
+		}
+	}
+
+	@layer test {}
+
+
+	@supports (min-width: 1px) {
+		@layer deep {
+			layer-deep {}
+
+		}
+	}
+}
+
+test {
+	a: 1;
+}
+
+@layer components {
+	@layer alert {}
+
+
+	@layer table {
+		@layer tbody, thead;
+
+		layer-components-table {
+			color: yellow;
+		}
+
+		@layer tbody {
+			tbody {
+				border: 1px solid;
+				background: red;
+			}
+		}
+
+		@media (min-width: 30em) {
+			@supports (display: grid) {
+				@layer thead {
+					thead {
+						border: 1px solid;
+					}
+				}
+			}
+		}
+	}
+}
+
+@layer components.breadcrumb {
+	layer-components-breadcrumb {}
+
+}
+
+@font-face {
+	font-family: "Test";
+	src: url(some-url.woff2);
+}
+
+;;;;;;;;;;;;;;;;;;;`
+	assert.equal(actual, expected);
+});
+
+test.run();