@taiga-ui/prettier-config 0.489.0 → 0.491.0

package/README.md

@@ -15,3 +15,66 @@ npm i --save-dev @taiga-ui/prettier-config
 ```js
 module.exports = require('@taiga-ui/prettier-config');
 ```
+
+## Internal Prettier plugins
+
+The package ships with three internal Prettier plugins that extend default Prettier behavior for project-specific
+formatting cases.
+
+### `prettier-plugin-css-custom-properties`
+
+Used for CSS-family files: `*.css`, `*.scss`, and `*.less`.
+
+- Reuses Prettier built-in PostCSS parsers for CSS, SCSS, and LESS.
+- Keeps CSS custom property declarations on one line, even when the declaration is longer than `printWidth`.
+- Applies only to declarations whose property name starts with `--`.
+- Leaves regular CSS, SCSS, and LESS declarations formatted by the original Prettier printer.
+
+```css
+:root {
+  --tui-font-offset: 0;
+  --tui-typography-family-display: inherit;
+  --tui-typography-heading-h1: bold calc(var(--tui-font-offset) + 3.125rem) / calc(56 / 50) var(--tui-typography-family-display);
+}
+```
+
+### `prettier-plugin-embedded-ts`
+
+Used for TypeScript files through the `typescript-embedded-ts` parser.
+
+- Reuses Prettier built-in TypeScript parser and ESTree printer.
+- Formats template literals as embedded TypeScript when they are preceded directly by a `/* TS */` or `/* TYPESCRIPT */`
+  block comment.
+- Marker matching is case-insensitive.
+- Formats only plain template literals without expressions.
+- Respects Prettier's `embeddedLanguageFormatting: 'off'` option and falls back to the default printer when embedded
+  formatting is disabled.
+
+```ts
+const code = /* TypeScript */ `
+    const value = {foo: 'bar'};
+`;
+```
+
+### `prettier-plugin-sort`
+
+Used for selected JSON files with the `json-stringify` parser:
+
+- `package.json`
+- `ng-package.json`
+- `project.json`
+- `renovate.json`
+- `default.json`
+- `tsconfig*.json`
+
+Capabilities:
+
+- Sorts `package.json` with `sort-package-json`.
+- Preserves the original order of `package.json` scripts.
+- Sorts `tsconfig*.json` top-level keys in this order: `$schema`, `extends`, `compileOnSave`, `compilerOptions`,
+  `angularCompilerOptions`, `files`, `include`, `exclude`, `references`; unknown keys are appended alphabetically.
+- Sorts `compilerOptions` with `baseUrl`, `rootDir`, and `strict` first; the rest are appended alphabetically.
+- Recursively sorts nested object keys alphabetically.
+- Preserves array item order.
+- Keeps arrays with one or two primitive values on one line for JSON files except `package.json`.
+- Leaves objects expanded through Prettier's original JSON printer.

package/index.js

@@ -5,6 +5,13 @@ module.exports = {
     plugins: [
         require.resolve('stylelint-prettier'),
         require.resolve('prettier-plugin-organize-attributes'),
+        require.resolve(
+            path.resolve(
+                __dirname,
+                'plugins',
+                'prettier-plugin-css-custom-properties.js',
+            ),
+        ),
     ],
     arrowParens: 'always',
     bracketSpacing: false,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@taiga-ui/prettier-config",
-    "version": "0.489.0",
+    "version": "0.491.0",
     "description": "Taiga-ui prettier config",
     "keywords": [
         "prettier",
@@ -32,7 +32,7 @@
     "main": "index.js",
     "peerDependencies": {
         "@prettier/plugin-xml": "^3.4.2",
-        "prettier": "^3.8.2",
+        "prettier": "^3.8.3",
         "prettier-package-json": "^2.8.0",
         "prettier-plugin-organize-attributes": "^1.0.0",
         "sort-package-json": "^3.6.1",

package/plugins/prettier-plugin-css-custom-properties.js

@@ -0,0 +1,146 @@
+const postcss = require('prettier/plugins/postcss');
+
+const AST_FORMAT = 'postcss-custom-properties';
+const originalPostcssPrinter = postcss.printers.postcss;
+
+/**
+ * @param {unknown} node
+ * @returns {node is {type: string; prop: string; value: string}}
+ */
+function isCustomPropertyDeclaration(node) {
+    return (
+        typeof node === 'object' &&
+        node !== null &&
+        'type' in node &&
+        'prop' in node &&
+        node.type === 'css-decl' &&
+        typeof node.prop === 'string' &&
+        node.prop.startsWith('--')
+    );
+}
+
+/**
+ * Returns true when a Prettier doc contains comment text (`//` or `/*`).
+ * Checking the printed doc is more reliable than checking `node.value` because
+ * postcss may store inline comments in `node.raws` rather than `node.value`.
+ *
+ * @param {import('prettier').Doc} doc
+ * @returns {boolean}
+ */
+function docContainsComment(doc) {
+    if (typeof doc === 'string') {
+        return doc.includes('//') || doc.includes('/*');
+    }
+
+    if (Array.isArray(doc)) {
+        return doc.some(docContainsComment);
+    }
+
+    if (typeof doc !== 'object' || doc === null) {
+        return false;
+    }
+
+    if (doc.type === 'fill') {
+        return doc.parts.some(docContainsComment);
+    }
+
+    if (doc.type === 'if-break') {
+        return (
+            docContainsComment(doc.breakContents) || docContainsComment(doc.flatContents)
+        );
+    }
+
+    if ('contents' in doc) {
+        return docContainsComment(doc.contents);
+    }
+
+    return false;
+}
+
+/**
+ * Converts a Prettier doc to its flat representation so custom properties are
+ * not wrapped by printWidth.
+ *
+ * @param {import('prettier').Doc} doc
+ * @returns {import('prettier').Doc}
+ */
+function flattenDoc(doc) {
+    if (typeof doc === 'string') {
+        return doc;
+    }
+
+    if (Array.isArray(doc)) {
+        return doc.map(flattenDoc);
+    }
+
+    switch (doc.type) {
+        case 'align':
+            return flattenDoc(doc.contents);
+
+        case 'break-parent':
+        case 'cursor':
+            return '';
+
+        case 'fill':
+            return doc.parts.map(flattenDoc);
+
+        case 'group':
+            return flattenDoc(doc.contents);
+
+        case 'if-break':
+            return flattenDoc(doc.flatContents);
+
+        case 'indent':
+            return flattenDoc(doc.contents);
+
+        case 'indent-if-break':
+            return '';
+
+        case 'label':
+            return flattenDoc(doc.contents);
+
+        case 'line':
+            return doc.soft ? '' : ' ';
+
+        case 'line-suffix':
+            return flattenDoc(doc.contents);
+
+        case 'line-suffix-boundary':
+        case 'trim':
+            return '';
+
+        default:
+            return doc;
+    }
+}
+
+exports.printers = {
+    [AST_FORMAT]: {
+        ...originalPostcssPrinter,
+        /**
+         * @param {import('prettier').AstPath} path
+         * @param {import('prettier').ParserOptions} options
+         * @param {(path: import('prettier').AstPath) => import('prettier').Doc} print
+         * @returns {import('prettier').Doc}
+         */
+        print(path, options, print) {
+            const printed = originalPostcssPrinter.print(path, options, print);
+
+            if (!isCustomPropertyDeclaration(path.node)) {
+                return printed;
+            }
+
+            return docContainsComment(printed) ? printed : flattenDoc(printed);
+        },
+    },
+};
+
+exports.parsers = Object.fromEntries(
+    Object.entries(postcss.parsers).map(([name, parser]) => [
+        name,
+        {
+            ...parser,
+            astFormat: AST_FORMAT,
+        },
+    ]),
+);

package/project.json

@@ -1,15 +0,0 @@
-{
-    "$schema": "../../node_modules/nx/schemas/project-schema.json",
-    "name": "prettier-config",
-    "prefix": "tui",
-    "projectType": "library",
-    "sourceRoot": "projects/prettier-config",
-    "targets": {
-        "publish": {
-            "executor": "nx:run-commands",
-            "options": {
-                "command": "npm publish ./projects/{projectName} --access=public --ignore-scripts"
-            }
-        }
-    }
-}