@culur/prettier-plugin-tailwindcss-group 1.1.0

package/src/handle-node/handle-cva-class-value.ts

@@ -0,0 +1,47 @@
+import type { Expression } from 'estree-jsx';
+import type { PluginOptions } from '../prettier';
+import {
+  isArrayExpression,
+  isCallExpression,
+  isIdentifier,
+  isStringLiteral,
+} from '../ast';
+import { handleExpressionArray } from './handle-expressions';
+import { handleStringLiteral } from './handle-string-literal';
+
+/** Handles a class value expression (StringLiteral, CallExpression, or ArrayExpression) inside `cva(...)`. */
+export function handleCvaClassValue(
+  expression: Expression,
+  options: PluginOptions,
+): Expression {
+  // Case 1: Plain string literal, e.g. "px-4 py-2" -> converts to string array if threshold exceeded
+  if (isStringLiteral(expression)) {
+    return handleStringLiteral(expression, options, 'cva');
+  }
+
+  // Case 2: Tailwind helper function call, e.g. cn("px-4", "py-2", dynamic)
+  if (
+    isCallExpression(expression) &&
+    isIdentifier(expression.callee, options.tailwindFunctions)
+  ) {
+    const result = handleExpressionArray(expression.arguments, options);
+    if (Array.isArray(result)) {
+      expression.arguments = result;
+      return expression;
+    }
+    return result;
+  }
+
+  // Case 3: Array of class expressions, e.g. ["px-4", "py-2", dynamic]
+  if (isArrayExpression(expression)) {
+    const result = handleExpressionArray(expression.elements, options);
+    if (Array.isArray(result)) {
+      expression.elements = result;
+      return expression;
+    }
+    return result;
+  }
+
+  // Fallback: Return expression unchanged if unrecognized
+  return expression;
+}

package/src/handle-node/handle-expressions.test.ts

@@ -0,0 +1,140 @@
+import dedent from 'dedent';
+import { describe } from 'vitest';
+import { testFormat } from '../__tests__/utils/test-format';
+
+describe('handle-expressions: no static strings / dynamic only', () => {
+  testFormat(
+    'leaves empty function call untouched',
+    { classNameThreshold: 5 },
+    dedent /* tsx */ ` <div className={cn()} />; `,
+    dedent /* tsx */ ` <div className={cn()} />; `,
+  );
+
+  testFormat(
+    'leaves dynamic-only arguments untouched',
+    { classNameThreshold: 5 },
+    dedent /* tsx */ ` <div className={cn(isActive && 'text-sm')} />; `,
+    dedent /* tsx */ ` <div className={cn(isActive && 'text-sm')} />; `,
+  );
+});
+
+describe('handle-expressions: empty and whitespace-only static strings', () => {
+  testFormat(
+    'simplifies pure empty string literal to empty string literal',
+    { classNameThreshold: 5 },
+    dedent /* tsx */ ` <div className={cn('')} />; `,
+    dedent /* tsx */ ` <div className="" />; `,
+  );
+
+  testFormat(
+    'strips whitespace-only static strings when dynamic arguments exist',
+    { classNameThreshold: 5 },
+    dedent /* tsx */ `
+      <div className={cn(' ', '   ', isEnabled && 'text-bold')} />;
+    `,
+    dedent /* tsx */ ` <div className={cn(isEnabled && 'text-bold')} />; `,
+  );
+
+  testFormat(
+    'strips multiple pure empty strings when dynamic arguments exist',
+    { classNameThreshold: 5 },
+    dedent /* tsx */ `
+      <div className={cn('', '', '', isActive && 'text-sm')} />;
+    `,
+    dedent /* tsx */ ` <div className={cn(isActive && 'text-sm')} />; `,
+  );
+
+  testFormat(
+    'simplifies whitespace-only static string to empty string literal',
+    { classNameThreshold: 5 },
+    dedent /* tsx */ ` <div className={cn('   ')} />; `,
+    dedent /* tsx */ ` <div className="" />; `,
+  );
+});
+
+describe('handle-expressions: class count within threshold (<= classNameThreshold)', () => {
+  testFormat(
+    'simplifies single static string to StringLiteral',
+    { classNameThreshold: 5 },
+    dedent /* tsx */ ` <div className={cn('text-sm font-bold')} />; `,
+    dedent /* tsx */ ` <div className="text-sm font-bold" />; `,
+  );
+
+  testFormat(
+    'merges multiple static string arguments into single StringLiteral',
+    { classNameThreshold: 5 },
+    dedent /* tsx */ `
+      <div className={cn('flex items-center', 'text-sm font-bold')} />;
+    `,
+    dedent /* tsx */ `
+      <div className="flex items-center text-sm font-bold" />;
+    `,
+  );
+
+  testFormat(
+    'merges static strings but preserves CallExpression when dynamic arguments exist',
+    { classNameThreshold: 5 },
+    dedent /* tsx */ `
+      <div className={cn('flex', 'items-center', isActive && 'text-sm')} />;
+    `,
+    dedent /* tsx */ `
+      <div className={cn('flex items-center', isActive && 'text-sm')} />;
+    `,
+  );
+});
+
+describe('handle-expressions: class count exceeds threshold (> classNameThreshold)', () => {
+  testFormat(
+    'groups static classes into multiple StringLiterals',
+    { classNameThreshold: 1 },
+    dedent /* tsx */ ` <div className={cn('text-sm font-bold')} />; `,
+    dedent /* tsx */ ` <div className={cn('text-sm font-bold')} />; `,
+  );
+
+  testFormat(
+    'gathers scattered static strings to front, groups them, and keeps dynamic arguments at end',
+    { classNameThreshold: 4 },
+    dedent /* tsx */ `
+      <div
+        className={cn(
+          isActive && 'bg-blue-500',
+          'flex items-center text-sm font-bold',
+          { 'opacity-50': disabled },
+          'p-4',
+        )}
+      />;
+    `,
+    dedent /* tsx */ `
+      <div
+        className={cn(
+          'flex items-center',
+          'p-4',
+          'text-sm font-bold',
+          isActive && 'bg-blue-500',
+          { 'opacity-50': disabled },
+        )}
+      />;
+    `,
+  );
+
+  testFormat(
+    'uses default options threshold for regrouping',
+    {},
+    dedent /* tsx */ `
+      <div
+        className={cn(
+          isActive && 'text-sm',
+          'c1 c2 c3 c4 c5 c6 c7 c8 c9 c10 c11 c12 c13 c14 c15 c16 c17 c18 c19 c20 c21',
+        )}
+      />;
+    `,
+    dedent /* tsx */ `
+      <div
+        className={cn(
+          'c1 c2 c3 c4 c5 c6 c7 c8 c9 c10 c11 c12 c13 c14 c15 c16 c17 c18 c19 c20 c21',
+          isActive && 'text-sm',
+        )}
+      />;
+    `,
+  );
+});

package/src/handle-node/handle-expressions.ts

@@ -0,0 +1,63 @@
+import type { Expression, SpreadElement } from 'estree-jsx';
+import type { StringLiteral } from '../ast';
+import type { PluginOptions } from '../prettier';
+import {
+  buildStringLiteral,
+  isNodeWithComments,
+  isStringLiteral,
+} from '../ast';
+import { groupClasses } from '../group-classes/group-classes';
+import { splitClasses } from '../utils/split-classes';
+
+/** Extracts and regroups static class strings in an expression array while preserving dynamic elements. */
+export function handleExpressionArray<
+  T extends Expression | SpreadElement | null,
+>(expressions: T[], options: PluginOptions): T[] | StringLiteral {
+  const staticStrings: string[] = [];
+  const dynamicExpressions: T[] = [];
+
+  // Separate static string literals from dynamic expressions
+  for (const arg of expressions) {
+    if (isStringLiteral(arg)) {
+      // BAIL OUT: If the string literal has attached comments, we must not touch it.
+      // Modifying or regrouping strings would destroy the AST comment locations,
+      // causing Prettier to throw "Comment was not printed" errors or misplace comments.
+      if (isNodeWithComments(arg)) {
+        return expressions;
+      }
+      staticStrings.push(arg.value);
+    } else {
+      dynamicExpressions.push(arg);
+    }
+  }
+
+  // Nothing to group if there are no static strings
+  if (staticStrings.length === 0) return expressions;
+
+  const combinedString = staticStrings.join(' ');
+  const classes = splitClasses(combinedString);
+
+  // Case 1: No static classes found (e.g. empty or whitespace-only strings)
+  if (classes.length === 0) {
+    return dynamicExpressions.length === 0
+      ? buildStringLiteral('')
+      : dynamicExpressions;
+  }
+
+  // Case 2: Class count is within threshold -> keep as a single string literal
+  if (classes.length <= options.classNameThreshold) {
+    const node = buildStringLiteral(combinedString) as unknown as T;
+    return dynamicExpressions.length === 0
+      ? (node as unknown as StringLiteral)
+      : [node, ...dynamicExpressions];
+  }
+
+  // Case 3: Class count exceeds threshold -> group into multiple string literals
+  const grouped = groupClasses(classes, options.modifierThreshold).map(
+    buildStringLiteral,
+  ) as unknown as T[];
+
+  return dynamicExpressions.length === 0
+    ? grouped
+    : [...grouped, ...dynamicExpressions];
+}

package/src/handle-node/handle-string-literal.test.ts

@@ -0,0 +1,135 @@
+import dedent from 'dedent';
+import { describe } from 'vitest';
+import { testFormat } from '../__tests__/utils/test-format';
+
+describe('handle-string-literal: jsx target (target = "jsx")', () => {
+  testFormat(
+    'leaves StringLiteral unchanged when class count <= threshold',
+    { classNameThreshold: 5 },
+    dedent /* tsx */ ` <div className="btn primary active" />; `,
+    dedent /* tsx */ ` <div className="btn primary active" />; `,
+  );
+
+  testFormat(
+    'wraps in JSXExpressionContainer with helper function call when > threshold',
+    { classNameThreshold: 4 },
+    dedent /* tsx */ `
+      <div className="flex items-center justify-center text-sm font-bold bg-white shadow-md border-gray-200" />;
+    `,
+    dedent /* tsx */ `
+      <div
+        className={cn(
+          'flex items-center justify-center',
+          'text-sm font-bold',
+          'bg-white',
+          'shadow-md border-gray-200',
+        )}
+      />;
+    `,
+  );
+
+  testFormat(
+    'uses first function from tailwindFunctions as wrapper name',
+    { classNameThreshold: 2, tailwindFunctions: ['clsx', 'cva'] },
+    dedent /* tsx */ `
+      <div className="flex items-center text-sm font-bold" />;
+    `,
+    dedent /* tsx */ `
+      <div className={clsx('flex items-center', 'text-sm font-bold')} />;
+    `,
+  );
+});
+
+describe('handle-string-literal: cva target (target = "cva")', () => {
+  testFormat(
+    'leaves StringLiteral unchanged when class count <= threshold',
+    { classNameThreshold: 5 },
+    dedent /* ts */ ` const b = cva('flex items-center'); `,
+    dedent /* ts */ ` const b = cva('flex items-center'); `,
+  );
+
+  testFormat(
+    'converts to StringArrayExpression when class count > threshold',
+    { classNameThreshold: 4 },
+    dedent /* ts */ `
+      const b = cva(
+        'flex items-center justify-center text-sm font-bold bg-white',
+      );
+    `,
+    dedent /* ts */ `
+      const b = cva([
+        'flex items-center justify-center',
+        'text-sm font-bold',
+        'bg-white',
+      ]);
+    `,
+  );
+});
+
+describe('handle-string-literal: complex class tokens and whitespace handling', () => {
+  testFormat(
+    'correctly groups important modifier ! classes',
+    { classNameThreshold: 4 },
+    dedent /* tsx */ `
+      <div className="absolute top-0 !font-bold text-sm !bg-red-500 bg-white shadow-md" />;
+    `,
+    dedent /* tsx */ `
+      <div
+        className={cn(
+          'absolute top-0',
+          '!font-bold text-sm',
+          '!bg-red-500 bg-white',
+          'shadow-md',
+        )}
+      />;
+    `,
+  );
+
+  testFormat(
+    'correctly groups negative numeric - classes',
+    { classNameThreshold: 4 },
+    dedent /* tsx */ `
+      <div className="-top-4 -left-2 text-sm font-bold -m-4 -p-2 shadow-md" />;
+    `,
+    dedent /* tsx */ `
+      <div
+        className={cn(
+          '-top-4 -left-2',
+          '-m-4 -p-2',
+          'text-sm font-bold',
+          'shadow-md',
+        )}
+      />;
+    `,
+  );
+
+  testFormat(
+    'correctly groups pseudo/variant prefixes with important modifier ! and negative -',
+    { classNameThreshold: 4 },
+    dedent /* tsx */ `
+      <div className="md:hover:!text-sm hover:!bg-red-500 dark:hover:-top-2 [&_p]:-mt-4 shadow-md" />;
+    `,
+    dedent /* tsx */ `
+      <div
+        className={cn(
+          'dark:hover:-top-2',
+          '[&_p]:-mt-4',
+          'md:hover:!text-sm',
+          'hover:!bg-red-500',
+          'shadow-md',
+        )}
+      />;
+    `,
+  );
+
+  testFormat(
+    'handles extra whitespace in class string',
+    { classNameThreshold: 2 },
+    dedent /* tsx */ `
+      <div className="  text-sm   font-bold   bg-white  " />;
+    `,
+    dedent /* tsx */ `
+      <div className={cn('text-sm font-bold', 'bg-white')} />;
+    `,
+  );
+});

package/src/handle-node/handle-string-literal.ts

@@ -0,0 +1,53 @@
+import type { JSXExpressionContainer } from 'estree-jsx';
+import type { StringArrayExpression, StringLiteral } from '../ast';
+import type { PluginOptions } from '../prettier';
+import {
+  buildCallExpression,
+  buildExpressionContainer,
+  buildStringArrayExpression,
+  buildStringLiteral,
+  isNodeWithComments,
+} from '../ast';
+import { groupClasses } from '../group-classes/group-classes';
+import { splitClasses } from '../utils/split-classes';
+
+export function handleStringLiteral(
+  node: StringLiteral,
+  options: PluginOptions,
+  target: 'jsx',
+): JSXExpressionContainer | StringLiteral;
+export function handleStringLiteral(
+  node: StringLiteral,
+  options: PluginOptions,
+  target: 'cva',
+): StringArrayExpression | StringLiteral;
+/** Processes a static string literal, grouping Tailwind CSS classes if threshold is exceeded. */
+export function handleStringLiteral(
+  node: StringLiteral,
+  options: PluginOptions,
+  target: 'jsx' | 'cva',
+): JSXExpressionContainer | StringArrayExpression | StringLiteral {
+  // BAIL OUT: If the string literal has attached comments, we must not touch it.
+  if (isNodeWithComments(node)) {
+    return node;
+  }
+
+  const classes = splitClasses(node.value);
+
+  // Keep as single string literal if class count is within threshold
+  if (classes.length <= options.classNameThreshold) return node;
+
+  // Group classes into logical clusters
+  const groups = groupClasses(classes, options.modifierThreshold);
+
+  // CVA context: transform into an ArrayExpression of string literals
+  if (target === 'cva') {
+    return buildStringArrayExpression(groups);
+  }
+
+  // JSX context: wrap grouped string literals in primary tailwind helper function (e.g. cn(...))
+  const wrapperName = options.tailwindFunctions[0];
+  const stringLiterals = groups.map(buildStringLiteral);
+  const expressionCall = buildCallExpression(wrapperName, stringLiterals);
+  return buildExpressionContainer(expressionCall);
+}

package/src/handle-targets/index.ts

@@ -0,0 +1,3 @@
+export { handleTargetCVA } from './target-cva';
+export { handleTargetJSX } from './target-jsx';
+export { handleTargetObjectProperty } from './target-object-properties';

package/src/handle-targets/target-cva-base.test.ts

@@ -0,0 +1,103 @@
+import dedent from 'dedent';
+import { describe } from 'vitest';
+import { testFormat } from '../__tests__/utils/test-format';
+
+describe('target-cva-base: missing or spread base arguments', () => {
+  testFormat(
+    'ignores cva() without arguments',
+    { classNameThreshold: 4 },
+    dedent /* ts */ ` const b = cva(); `,
+    dedent /* ts */ ` const b = cva(); `,
+  );
+
+  testFormat(
+    'ignores cva(...args) with SpreadElement base',
+    { classNameThreshold: 4 },
+    dedent /* ts */ ` const b = cva(...args); `,
+    dedent /* ts */ ` const b = cva(...args); `,
+  );
+});
+
+describe('target-cva-base: stringLiteral base', () => {
+  testFormat(
+    'converts to StringArrayExpression when class count > threshold',
+    { classNameThreshold: 4 },
+    dedent /* ts */ `
+      const b = cva(
+        'flex items-center justify-center text-sm font-bold bg-white',
+      );
+    `,
+    dedent /* ts */ `
+      const b = cva([
+        'flex items-center justify-center',
+        'text-sm font-bold',
+        'bg-white',
+      ]);
+    `,
+  );
+
+  testFormat(
+    'stays StringLiteral when class count <= threshold',
+    { classNameThreshold: 5 },
+    dedent /* ts */ ` const b = cva('flex items-center'); `,
+    dedent /* ts */ ` const b = cva('flex items-center'); `,
+  );
+});
+
+describe('target-cva-base: arrayExpression base', () => {
+  testFormat(
+    'flattens and regroups when class count > threshold',
+    { classNameThreshold: 4 },
+    dedent /* ts */ `
+      const b = cva([
+        'flex items-center justify-center',
+        'text-sm font-bold bg-white',
+      ]);
+    `,
+    dedent /* ts */ `
+      const b = cva([
+        'flex items-center justify-center',
+        'text-sm font-bold',
+        'bg-white',
+      ]);
+    `,
+  );
+
+  testFormat(
+    'simplifies to StringLiteral when class count <= threshold',
+    { classNameThreshold: 10 },
+    dedent /* ts */ ` const b = cva(['flex', 'items-center']); `,
+    dedent /* ts */ ` const b = cva('flex items-center'); `,
+  );
+
+  testFormat(
+    'preserves dynamic elements in array base',
+    { classNameThreshold: 1 },
+    dedent /* ts */ ` const b = cva([isActive && 'bg-blue-500']); `,
+    dedent /* ts */ ` const b = cva([isActive && 'bg-blue-500']); `,
+  );
+});
+
+describe('target-cva-base: callExpression base', () => {
+  testFormat(
+    'groups arguments when class count > threshold',
+    { classNameThreshold: 4 },
+    dedent /* ts */ `
+      const b = cva(
+        cn('flex items-center justify-center text-sm font-bold bg-white'),
+      );
+    `,
+    dedent /* ts */ `
+      const b = cva(
+        cn('flex items-center justify-center', 'text-sm font-bold', 'bg-white'),
+      );
+    `,
+  );
+
+  testFormat(
+    'simplifies to StringLiteral when class count <= threshold',
+    { classNameThreshold: 10 },
+    dedent /* ts */ ` const b = cva(cn('flex', 'items-center')); `,
+    dedent /* ts */ ` const b = cva('flex items-center'); `,
+  );
+});

package/src/handle-targets/target-cva-base.ts

@@ -0,0 +1,17 @@
+import type { CallExpression } from 'estree-jsx';
+import type { PluginOptions } from '../prettier';
+import { handleCvaClassValue } from '../handle-node/handle-cva-class-value';
+
+/** Processes base class value (params[0]) in a `cva(...)` call. */
+export function handleTargetCvaBase(
+  cva: CallExpression,
+  options: PluginOptions,
+): void {
+  const base = cva.arguments[0];
+
+  // Base argument does not exist or is a SpreadElement (...args)
+  if (!base || base.type === 'SpreadElement') return;
+
+  // Transform base class value (string literal, function call, or array)
+  cva.arguments[0] = handleCvaClassValue(base, options);
+}