@culur/prettier-plugin-tailwindcss-group 1.1.0

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@culur/prettier-plugin-tailwindcss-group",
+  "version": "1.1.0",
+  "description": "Prettier plugin to automatically format and wrap long className attributes",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/culur/culur.git",
+    "directory": "packages/prettier-plugin-tailwindcss-group"
+  },
+  "bugs": {
+    "url": "https://github.com/culur/culur/issues"
+  },
+  "homepage": "https://github.com/culur/culur/tree/main/packages/prettier-plugin-tailwindcss-group#readme",
+  "author": "culur <culur.net@gmail.com>",
+  "license": "MIT",
+  "keywords": [
+    "culur",
+    "prettier",
+    "prettier-plugin",
+    "classnames"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "!**/*.test.*",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "dist",
+    "src"
+  ],
+  "volta": {
+    "extends": "../../package.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@babel/parser": "^8.0.4",
+    "@types/estree-jsx": "^1.0.5",
+    "@types/react": "^19.2.18",
+    "dedent": "^1.7.2",
+    "prettier": "^3.9.6",
+    "prettier-plugin-tailwindcss": "^0.8.1",
+    "remark": "^15.0.1",
+    "remark-parse": "^11.0.0",
+    "tailwind-merge": "^3.6.0",
+    "@culur/config-eslint": "1.9.0",
+    "@culur/config-tsdown": "1.1.2",
+    "@culur/config-prettier": "1.5.0",
+    "@culur/config-typescript": "2.0.0",
+    "@culur/config-vite": "1.5.2"
+  },
+  "peerDependencies": {
+    "prettier": ">=3.0.0",
+    "prettier-plugin-tailwindcss": ">=0.6.0"
+  }
+}

package/src/__tests__/comments.test.ts

@@ -0,0 +1,171 @@
+import type { Plugin } from 'prettier';
+import dedent from 'dedent';
+import * as tailwindPlugin from 'prettier-plugin-tailwindcss';
+import { describe } from 'vitest';
+import plugin from '../index';
+import { testFormat } from './utils/test-format';
+
+describe('comment preservation in cn() and cva([])', () => {
+  const options = {
+    plugins: [plugin, tailwindPlugin as unknown as Plugin],
+    classNameThreshold: 5,
+    tailwindFunctions: ['cn'],
+  };
+
+  testFormat(
+    'succeeds for comments outside of cn() arguments',
+    options,
+    dedent`
+      // Component comment
+      <div
+        // Attribute comment
+        className={cn('flex items-center justify-center text-sm font-bold bg-white shadow-md')} // End of JSX attribute
+      />;
+    `,
+    dedent`
+      // Component comment
+      <div
+        // Attribute comment
+        className={cn(
+          'flex items-center justify-center',
+          'text-sm font-bold',
+          'bg-white',
+          'shadow-md',
+        )} // End of JSX attribute
+      />;
+    `,
+  );
+
+  testFormat(
+    'bails out and preserves comments when placed inside cn() or end-of-line',
+    options,
+    dedent`
+      <div
+        className={cn(
+          // Inner layout comment
+          'flex items-center', // Trailing comment
+          'bg-red-500 text-white font-bold p-4 shadow-md',
+        )}
+      />;
+    `,
+    // Since it bails out, it keeps the original formatting of the strings,
+    // but prettier-plugin-tailwindcss core still sorts the classes inside the string.
+    dedent`
+      <div
+        className={cn(
+          // Inner layout comment
+          'flex items-center', // Trailing comment
+          'bg-red-500 p-4 font-bold text-white shadow-md',
+        )}
+      />;
+    `,
+  );
+
+  testFormat(
+    'bails out for comments inside cva([]) array',
+    options,
+    dedent`
+      const button = cva([
+        // Array item comment
+        'inline-flex items-center justify-center rounded-md text-sm font-medium p-4 bg-primary',
+      ]);
+    `,
+    dedent`
+      const button = cva([
+        // Array item comment
+        'inline-flex items-center justify-center rounded-md text-sm font-medium p-4 bg-primary',
+      ]);
+    `,
+  );
+
+  testFormat(
+    'preserves sparse array hole on comment bail-out in cva([]) array',
+    options,
+    dedent`
+      const button = cva([
+        ,
+        // Array item comment
+        'inline-flex items-center justify-center rounded-md text-sm font-medium p-4 bg-primary',
+      ]);
+    `,
+    dedent`
+      const button = cva([
+        ,
+        // Array item comment
+        'inline-flex items-center justify-center rounded-md text-sm font-medium p-4 bg-primary',
+      ]);
+    `,
+  );
+
+  testFormat(
+    'bails out when simplifying short string with comments',
+    { ...options, classNameThreshold: 10 },
+    dedent`
+      <div
+        className={cn(
+          // short comment
+          'flex items-center',
+        )}
+      />;
+    `,
+    dedent`
+      <div
+        className={cn(
+          // short comment
+          'flex items-center',
+        )}
+      />;
+    `,
+  );
+
+  testFormat(
+    'bails out when a bare className string literal has comments attached',
+    options,
+    dedent`
+      <div
+        className={
+          /* comment attached to literal */
+          'flex items-center justify-center p-4 bg-red-500 shadow-md text-white'
+        }
+      />;
+    `,
+    // Note: prettier core simplifies literal string in {} when possible,
+    // but because there is a comment inside {}, it preserves the block.
+    dedent`
+      <div
+        className={
+          /* comment attached to literal */
+          'flex items-center justify-center bg-red-500 p-4 text-white shadow-md'
+        }
+      />;
+    `,
+  );
+
+  testFormat(
+    'bails out when a plain className string literal has comments attached',
+    options,
+    dedent`
+      <div className=/* comment */"flex items-center justify-center p-4 bg-red-500 shadow-md text-white" />;
+    `,
+    dedent`
+      <div className=/* comment */ "flex items-center justify-center bg-red-500 p-4 text-white shadow-md" />;
+    `,
+  );
+
+  testFormat(
+    'bails out for comments on a bare cva string literal',
+    options,
+    dedent`
+      const button = cva(
+        /* comment */
+        'inline-flex items-center justify-center rounded-md text-sm font-medium p-4 bg-primary'
+      );
+    `,
+    dedent`
+      const button = cva(
+        /* comment */
+        'inline-flex items-center justify-center rounded-md text-sm font-medium p-4 bg-primary',
+      );
+    `,
+  );
+});

package/src/__tests__/plugin-official.test.ts

@@ -0,0 +1,32 @@
+import type { Plugin } from 'prettier';
+import dedent from 'dedent';
+import * as tailwindPlugin from 'prettier-plugin-tailwindcss';
+import { describe } from 'vitest';
+import plugin from '../index';
+import { testFormat } from './utils/test-format';
+
+describe('combined mode (with prettier-plugin-tailwindcss)', () => {
+  testFormat(
+    'allows prettier-plugin-tailwindcss to sort classes within group',
+    {
+      classNameThreshold: 5,
+      plugins: [plugin, tailwindPlugin as unknown as Plugin],
+    },
+    dedent /* tsx */ `
+      <div className="z-10 flex justify-center items-center p-4 font-bold text-white bg-red-500 bg-opacity-50 shadow-md shadow-black/50 opacity-50 mix-blend-multiply" />;
+    `,
+    dedent /* tsx */ `
+      <div
+        className={cn(
+          'z-10',
+          'flex items-center justify-center',
+          'p-4',
+          'font-bold text-white',
+          'bg-opacity-50 bg-red-500',
+          'shadow-md shadow-black/50',
+          'opacity-50 mix-blend-multiply',
+        )}
+      />;
+    `,
+  );
+});

package/src/__tests__/readme.test.ts

@@ -0,0 +1,13 @@
+import path from 'node:path';
+import { describe } from 'vitest';
+import { extractTestCasesFromMarkdown } from './utils/ast-md';
+import { testFormat } from './utils/test-format';
+
+describe('readme.md test cases', () => {
+  const readmePath = path.resolve(__dirname, '../../README.md');
+  const testCases = extractTestCasesFromMarkdown(readmePath);
+
+  for (const testCase of testCases) {
+    testFormat(testCase.id, testCase.options, testCase.input, testCase.expected);
+  }
+});

package/src/__tests__/utils/ast-estree.ts

@@ -0,0 +1,22 @@
+import type { Expression, ExpressionStatement, Node, Program } from 'estree-jsx';
+import { parse } from '@babel/parser';
+
+/**
+ * Parses source code into a standard ESTree Program AST node using @babel/parser with estree plugin.
+ */
+export function parseEstree(code: string): Program {
+  const file = parse(code, {
+    sourceType: 'module',
+    plugins: ['jsx', 'typescript', 'estree'],
+  });
+  return file.program as unknown as Program;
+}
+
+/**
+ * Parses a single JS/TS/JSX expression into an ESTree AST node.
+ */
+export function parseExpression<T extends Node = Expression>(code: string): T {
+  const program = parseEstree(`(${code})`);
+  const stmt = program.body[0] as ExpressionStatement;
+  return stmt.expression as T;
+}

package/src/__tests__/utils/ast-md.ts

@@ -0,0 +1,101 @@
+import type { Options, Plugin } from 'prettier';
+import fs from 'node:fs';
+import * as tailwindPlugin from 'prettier-plugin-tailwindcss';
+import { remark } from 'remark';
+import remarkParse from 'remark-parse';
+import plugin from '../..';
+
+export interface AstNode {
+  type: string;
+  [key: string]: unknown;
+}
+
+export interface ParentNode extends AstNode {
+  children: AstNode[];
+}
+
+export interface HtmlNode extends AstNode {
+  type: 'html';
+  value: string;
+}
+
+export interface CodeNode extends AstNode {
+  type: 'code';
+  lang?: string;
+  value: string;
+}
+
+export interface TestCase {
+  id: string;
+  options: Options;
+  input: string;
+  expected: string;
+}
+
+export function parseTestCaseOptions(metaStr: string): {
+  id: string;
+  options: Options;
+} {
+  const parts = metaStr.trim().split(/\s+/);
+  const id = parts[0] || 'unnamed-test';
+  const options: Options = {
+    plugins: [plugin, tailwindPlugin as unknown as Plugin],
+  };
+
+  for (let i = 1; i < parts.length; i++) {
+    const [key, val] = parts[i].split('=');
+    if (key && val) {
+      if (!Number.isNaN(Number(val))) {
+        options[key] = Number(val);
+      } else if (val === 'true' || val === 'false') {
+        options[key] = val === 'true';
+      } else {
+        options[key] = val;
+      }
+    }
+  }
+
+  return { id, options };
+}
+
+function normalizeJsx(code: string): string {
+  const trimmed = code.trim();
+  return trimmed.endsWith(';') ? trimmed : `${trimmed};`;
+}
+
+export function extractTestCasesFromMarkdown(filePath: string): TestCase[] {
+  const fileContent = fs.readFileSync(filePath, 'utf8');
+  const tree = remark().use(remarkParse).parse(fileContent) as unknown as ParentNode;
+  const testCases: TestCase[] = [];
+
+  const children = tree.children;
+  for (let i = 0; i < children.length; i++) {
+    const node = children[i];
+    if (node.type === 'html') {
+      const htmlNode = node as HtmlNode;
+      const match = htmlNode.value.match(/<!--\s*test-case:([^\n]+?)-->/);
+      if (match) {
+        const { id, options } = parseTestCaseOptions(match[1]);
+
+        // Look ahead for the next two `code` nodes
+        const codeNodes: CodeNode[] = [];
+        for (let j = i + 1; j < children.length && codeNodes.length < 2; j++) {
+          if (children[j].type === 'code') {
+            codeNodes.push(children[j] as CodeNode);
+          }
+        }
+
+        if (codeNodes.length === 2) {
+          testCases.push({
+            id,
+            options,
+            input: normalizeJsx(codeNodes[0].value),
+            expected: normalizeJsx(codeNodes[1].value),
+          });
+        }
+      }
+    }
+  }
+
+  return testCases;
+}

package/src/__tests__/utils/test-format.ts

@@ -0,0 +1,35 @@
+import type { Options } from 'prettier';
+import defineConfig from '@culur/config-prettier/factory';
+import prettier from 'prettier';
+import { expect, it } from 'vitest';
+import plugin from '../../index';
+
+const baseConfig = defineConfig();
+
+export function testFormat(
+  name: string,
+  options: Options,
+  code: string,
+  expected: string,
+): void {
+  it(name, async () => {
+    const pass1Config = {
+      ...baseConfig,
+      parser: 'typescript' as const,
+      plugins: [plugin],
+      ...options,
+    };
+
+    const formatted = await prettier.format(code, pass1Config);
+
+    expect(formatted).toBe(`${expected}\n`);
+
+    const pass2Config = {
+      ...pass1Config,
+      plugins: (pass1Config.plugins as any[]).filter((p: any) => p !== plugin),
+    };
+
+    const formattedWithoutPlugin = await prettier.format(formatted, pass2Config);
+    expect(formattedWithoutPlugin).toBe(formatted);
+  });
+}

package/src/ast/ast-array-expression.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import { parseExpression } from '../__tests__/utils/ast-estree';
+import {
+  buildStringArrayExpression,
+  isArrayExpression,
+} from './ast-array-expression';
+
+describe('ast-array-expression utils', () => {
+  describe('isArrayExpression', () => {
+    it('returns true for ArrayExpression nodes', () => {
+      const node = parseExpression('["flex", "p-4"]');
+      expect(isArrayExpression(node)).toBe(true);
+    });
+
+    it('returns false for other node types', () => {
+      const node = parseExpression('foo');
+      expect(isArrayExpression(node)).toBe(false);
+    });
+  });
+
+  describe('buildStringArrayExpression', () => {
+    it('builds an ArrayExpression from array of string groups', () => {
+      const result = buildStringArrayExpression(['flex items-center', 'p-4']);
+      expect(result.type).toBe('ArrayExpression');
+      expect(result.elements).toHaveLength(2);
+      expect(result.elements[0]).toEqual({
+        type: 'Literal',
+        value: 'flex items-center',
+        raw: JSON.stringify('flex items-center'),
+      });
+    });
+  });
+});

package/src/ast/ast-array-expression.ts

@@ -0,0 +1,20 @@
+import type { ArrayExpression, Node } from 'estree-jsx';
+import { buildStringLiteral } from './ast-literal';
+
+export type StringArrayExpression = ArrayExpression & {
+  elements: NonNullable<ArrayExpression['elements'][number]>[];
+};
+
+export function isArrayExpression(node: Node): node is ArrayExpression {
+  return node.type === 'ArrayExpression';
+}
+
+/** Builds an ArrayExpression of StringLiterals from grouped class strings. */
+export function buildStringArrayExpression(
+  groups: string[],
+): StringArrayExpression {
+  return {
+    type: 'ArrayExpression',
+    elements: groups.map(buildStringLiteral),
+  } satisfies StringArrayExpression;
+}

package/src/ast/ast-call-expression.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+import { parseExpression } from '../__tests__/utils/ast-estree';
+import { isCallExpression } from './ast-call-expression';
+
+describe('ast-call-expression utils', () => {
+  describe('isCallExpression', () => {
+    it('returns true for CallExpression nodes', () => {
+      const node = parseExpression('cn("flex")');
+      expect(isCallExpression(node)).toBe(true);
+    });
+
+    it('returns false for other node types', () => {
+      const node = parseExpression('foo');
+      expect(isCallExpression(node)).toBe(false);
+    });
+  });
+});

package/src/ast/ast-call-expression.ts

@@ -0,0 +1,5 @@
+import type { CallExpression, Node } from 'estree-jsx';
+
+export function isCallExpression(node: Node): node is CallExpression {
+  return node.type === 'CallExpression';
+}

package/src/ast/ast-comment.test.ts

@@ -0,0 +1,45 @@
+import type { ArrayExpression } from 'estree-jsx';
+import { assert, describe, expect, it } from 'vitest';
+import { parseExpression } from '../__tests__/utils/ast-estree';
+import { isNodeWithComments, type NodeWithComments } from './ast-comment';
+
+describe('isNodeWithComments (real ESTree parser output)', () => {
+  it('returns false for nodes without comments', () => {
+    const node = parseExpression('foo');
+    expect(isNodeWithComments(node)).toBe(false);
+    expect(isNodeWithComments(null)).toBe(false);
+    expect(isNodeWithComments(undefined)).toBe(false);
+  });
+
+  it('returns true when Prettier injects node.comments', () => {
+    const node: NodeWithComments = parseExpression('foo');
+    // Prettier internally maps leading/trailing comments into node.comments during print
+    node.comments = [{ type: 'Line', value: ' test' }];
+    expect(isNodeWithComments(node)).toBe(true);
+  });
+
+  it('detects leading comments from raw Babel ESTree', () => {
+    // We use an array so Babel attaches the comment to the inner element
+    const arrayNode = parseExpression<ArrayExpression>('[ /* lead */ foo ]');
+    const fooNode = arrayNode.elements[0]!;
+
+    assert(isNodeWithComments(fooNode));
+    expect(fooNode.leadingComments?.length).toBeGreaterThan(0);
+  });
+
+  it('detects trailing comments from raw Babel ESTree', () => {
+    const arrayNode = parseExpression<ArrayExpression>('[ foo /* trail */ ]');
+    const fooNode = arrayNode.elements[0]!;
+
+    assert(isNodeWithComments(fooNode));
+    expect(fooNode.trailingComments?.length).toBeGreaterThan(0);
+  });
+
+  it('returns false when comment arrays are explicitly empty', () => {
+    const node: NodeWithComments = parseExpression('foo');
+    node.comments = [];
+    node.leadingComments = [];
+    node.trailingComments = [];
+    expect(isNodeWithComments(node)).toBe(false);
+  });
+});

package/src/ast/ast-comment.ts

@@ -0,0 +1,25 @@
+import type { Node } from 'estree-jsx';
+
+export interface Comment {
+  type: 'Line' | 'Block' | string;
+  value: string;
+  [key: string]: unknown;
+}
+
+export type NodeWithComments<T extends Node = Node> = T & {
+  comments?: Comment[];
+  leadingComments?: Comment[];
+  trailingComments?: Comment[];
+};
+
+export function isNodeWithComments<T extends Node = Node>(
+  node?: T | null,
+): node is NodeWithComments<T> {
+  if (!node) return false;
+  const n = node as NodeWithComments<T>;
+  return Boolean(
+    (n.comments && n.comments.length > 0) ||
+    (n.leadingComments && n.leadingComments.length > 0) ||
+    (n.trailingComments && n.trailingComments.length > 0),
+  );
+}

package/src/ast/ast-common.ts

@@ -0,0 +1,29 @@
+import type { Identifier, Node } from 'estree-jsx';
+import type { Printer } from 'prettier';
+import estreePlugin from 'prettier/plugins/estree.js';
+
+export const estree = estreePlugin.printers.estree as Printer<Node>;
+
+export function isNode(value: unknown): value is Node {
+  const node = value as Node;
+  return (
+    node !== null && //
+    typeof node === 'object' &&
+    typeof node.type === 'string'
+  );
+}
+
+export function isIdentifier(
+  node: Node,
+  names?: string | string[],
+): node is Identifier {
+  if (node.type !== 'Identifier') return false;
+  if (names !== undefined) {
+    if (Array.isArray(names)) {
+      if (!names.includes(node.name)) return false;
+    } else if (node.name !== names) {
+      return false;
+    }
+  }
+  return true;
+}

package/src/ast/ast-jsx.test.ts

@@ -0,0 +1,56 @@
+import type { JSXAttribute, JSXElement } from 'estree-jsx';
+import { describe, expect, it } from 'vitest';
+import { parseExpression } from '../__tests__/utils/ast-estree';
+import {
+  isJSXAttribute,
+  isJSXExpressionContainer,
+  isJSXIdentifier,
+} from './ast-jsx';
+
+describe('ast-jsx utils', () => {
+  describe('isJSXAttribute', () => {
+    it('returns true for JSXAttribute nodes', () => {
+      const element = parseExpression<JSXElement>('<div className="flex" />');
+      const attr = element.openingElement.attributes[0];
+      expect(isJSXAttribute(attr)).toBe(true);
+    });
+
+    it('returns false for other node types', () => {
+      const node = parseExpression('foo');
+      expect(isJSXAttribute(node)).toBe(false);
+    });
+  });
+
+  describe('isJSXIdentifier', () => {
+    it('returns false if node type is not JSXIdentifier', () => {
+      const node = parseExpression('foo');
+      expect(isJSXIdentifier(node)).toBe(false);
+    });
+
+    it('returns true for JSXIdentifier when name is undefined', () => {
+      const element = parseExpression<JSXElement>('<div className="flex" />');
+      const attr = element.openingElement.attributes[0] as JSXAttribute;
+      expect(isJSXIdentifier(attr.name)).toBe(true);
+    });
+
+    it('handles name argument matching and non-matching', () => {
+      const element = parseExpression<JSXElement>('<div className="flex" />');
+      const attr = element.openingElement.attributes[0] as JSXAttribute;
+      expect(isJSXIdentifier(attr.name, 'className')).toBe(true);
+      expect(isJSXIdentifier(attr.name, 'id')).toBe(false);
+    });
+  });
+
+  describe('isJSXExpressionContainer', () => {
+    it('returns true for JSXExpressionContainer nodes', () => {
+      const element = parseExpression<JSXElement>('<div className={"flex"} />');
+      const attr = element.openingElement.attributes[0] as JSXAttribute;
+      expect(isJSXExpressionContainer(attr.value!)).toBe(true);
+    });
+
+    it('returns false for other node types', () => {
+      const node = parseExpression('foo');
+      expect(isJSXExpressionContainer(node)).toBe(false);
+    });
+  });
+});