@culur/prettier-plugin-tailwindcss-group 1.1.0

package/src/handle-targets/target-jsx.test.ts

@@ -0,0 +1,242 @@
+import dedent from 'dedent';
+import { describe } from 'vitest';
+import { testFormat } from '../__tests__/utils/test-format';
+
+describe('target-jsx: validation and bypassing unrelated attributes', () => {
+  testFormat(
+    'ignores non-className attributes such as id and style',
+    { classNameThreshold: 1 },
+    dedent /* tsx */ `
+      <div id="flex items-center text-sm font-bold" style="color: red" />;
+    `,
+    dedent /* tsx */ `
+      <div id="flex items-center text-sm font-bold" style="color: red" />;
+    `,
+  );
+
+  testFormat(
+    'ignores empty className attribute',
+    { classNameThreshold: 5 },
+    dedent /* tsx */ ` <div className="" />; `,
+    dedent /* tsx */ ` <div className="" />; `,
+  );
+
+  testFormat(
+    'ignores valueless className attribute',
+    { classNameThreshold: 5 },
+    dedent /* tsx */ ` <div className />; `,
+    dedent /* tsx */ ` <div className />; `,
+  );
+});
+
+describe('target-jsx: matching supported className patterns', () => {
+  testFormat(
+    'formats wrapperClassName when class count > threshold',
+    { classNameThreshold: 4 },
+    dedent /* tsx */ `
+      <div wrapperClassName="flex items-center justify-center text-sm font-bold bg-white shadow-md" />;
+    `,
+    dedent /* tsx */ `
+      <div
+        wrapperClassName={cn(
+          'flex items-center justify-center',
+          'text-sm font-bold',
+          'bg-white',
+          'shadow-md',
+        )}
+      />;
+    `,
+  );
+
+  testFormat(
+    'formats containerClassName when class count > threshold',
+    { classNameThreshold: 4 },
+    dedent /* tsx */ `
+      <div containerClassName="flex items-center justify-center text-sm font-bold bg-white shadow-md" />;
+    `,
+    dedent /* tsx */ `
+      <div
+        containerClassName={cn(
+          'flex items-center justify-center',
+          'text-sm font-bold',
+          'bg-white',
+          'shadow-md',
+        )}
+      />;
+    `,
+  );
+});
+
+describe('target-jsx: case 1: stringLiteral value', () => {
+  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 function call when class count > 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',
+        )}
+      />;
+    `,
+  );
+});
+
+describe('target-jsx: case 2: JSXExpressionContainer with stringLiteral', () => {
+  testFormat(
+    'simplifies to StringLiteral when class count <= threshold',
+    { classNameThreshold: 5 },
+    dedent /* tsx */ ` <div className={'btn primary active'} />; `,
+    dedent /* tsx */ ` <div className="btn primary active" />; `,
+  );
+
+  testFormat(
+    'wraps in function call when class count > threshold',
+    { classNameThreshold: 2 },
+    dedent /* tsx */ `
+      <div className={'flex items-center text-sm font-bold'} />;
+    `,
+    dedent /* tsx */ `
+      <div className={cn('flex items-center', 'text-sm font-bold')} />;
+    `,
+  );
+});
+
+describe('target-jsx: case 3: JSXExpressionContainer with callExpression', () => {
+  testFormat(
+    'simplifies single static string argument to StringLiteral if <= threshold',
+    { 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 and simplifies to StringLiteral if <= threshold',
+    { classNameThreshold: 5 },
+    dedent /* tsx */ ` <div className={cn('text-sm', 'font-bold')} />; `,
+    dedent /* tsx */ ` <div className="text-sm font-bold" />; `,
+  );
+
+  testFormat(
+    'groups static strings to front and preserves dynamic arguments when > threshold',
+    { 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(
+    'does not simplify when dynamic arguments exist even if static count <= threshold',
+    { classNameThreshold: 5 },
+    dedent /* tsx */ ` <div className={cn('flex', isActive && 'text-sm')} />; `,
+    dedent /* tsx */ ` <div className={cn('flex', isActive && 'text-sm')} />; `,
+  );
+
+  testFormat(
+    'ignores CallExpression with callee not in tailwindFunctions',
+    { classNameThreshold: 1, tailwindFunctions: ['cn'] },
+    dedent /* tsx */ `
+      <div className={unrelatedFn('flex items-center text-sm font-bold')} />;
+    `,
+    dedent /* tsx */ `
+      <div className={unrelatedFn('flex items-center text-sm font-bold')} />;
+    `,
+  );
+
+  testFormat(
+    'supports custom tailwindFunctions',
+    { classNameThreshold: 2, tailwindFunctions: ['clsx', 'cva'] },
+    dedent /* tsx */ `
+      <div
+        className={clsx(
+          'flex items-center text-sm font-bold',
+          isActive && 'bg-white',
+        )}
+      />;
+    `,
+    dedent /* tsx */ `
+      <div
+        className={clsx(
+          'flex items-center',
+          'text-sm font-bold',
+          isActive && 'bg-white',
+        )}
+      />;
+    `,
+  );
+
+  testFormat(
+    'preserves nested JSX element inside cn() arguments as dynamic expression',
+    { classNameThreshold: 2 },
+    dedent /* tsx */ `
+      <div
+        className={cn(
+          <span />,
+          'flex items-center justify-center text-sm font-bold bg-white',
+        )}
+      />;
+    `,
+    dedent /* tsx */ `
+      <div
+        className={cn(
+          'flex items-center justify-center',
+          'text-sm font-bold',
+          'bg-white',
+          <span />,
+        )}
+      />;
+    `,
+  );
+
+  testFormat(
+    'handles nested helper function call cn(...) inside outer cn(...) as dynamic argument',
+    { classNameThreshold: 2 },
+    dedent /* tsx */ `
+      <div
+        className={cn(
+          cn('text-sm font-bold', isActive && 'text-blue-500'),
+          'flex items-center bg-white',
+        )}
+      />;
+    `,
+    dedent /* tsx */ `
+      <div
+        className={cn(
+          'flex items-center',
+          'bg-white',
+          cn('text-sm font-bold', isActive && 'text-blue-500'),
+        )}
+      />;
+    `,
+  );
+});

package/src/handle-targets/target-jsx.ts

@@ -0,0 +1,65 @@
+import type { Node } from 'estree-jsx';
+import type { PluginOptions } from '../prettier';
+import {
+  isCallExpression,
+  isClassNameKey,
+  isIdentifier,
+  isJSXAttribute,
+  isJSXExpressionContainer,
+  isJSXIdentifier,
+  isNodeWithComments,
+  isStringLiteral,
+} from '../ast';
+import { handleExpressionArray } from '../handle-node/handle-expressions';
+import { handleStringLiteral } from '../handle-node/handle-string-literal';
+
+/** Handles JSX attribute formatting for `className` and `*ClassName` attributes. */
+export function handleTargetJSX(node: Node, options: PluginOptions): boolean {
+  // Validate that node is a JSXAttribute with a name matching className / *ClassName
+  if (
+    !isJSXAttribute(node) ||
+    !isJSXIdentifier(node.name) ||
+    !isClassNameKey(node.name.name) ||
+    !node.value
+  ) {
+    return false;
+  }
+
+  // Case 1: Plain string literal attribute value, e.g. `className="..."`
+  if (isStringLiteral(node.value)) {
+    node.value = handleStringLiteral(node.value, options, 'jsx');
+  }
+  // Case 2: JSX expression container with a string literal, e.g. `className={"..."}`
+  else if (
+    isJSXExpressionContainer(node.value) &&
+    isStringLiteral(node.value.expression)
+  ) {
+    if (
+      isNodeWithComments(node.value) ||
+      isNodeWithComments(node.value.expression)
+    ) {
+      return false;
+    }
+    node.value = handleStringLiteral(node.value.expression, options, 'jsx');
+  }
+  // Case 3: JSX expression container calling a tailwind helper function, e.g. `className={cn(...)}`
+  else if (
+    isJSXExpressionContainer(node.value) &&
+    isCallExpression(node.value.expression) &&
+    isIdentifier(node.value.expression.callee, options.tailwindFunctions)
+  ) {
+    const result = handleExpressionArray(
+      node.value.expression.arguments,
+      options,
+    );
+
+    // If result is an expression array, update function arguments; otherwise replace expression
+    if (Array.isArray(result)) {
+      node.value.expression.arguments = result;
+    } else {
+      node.value = result;
+    }
+  }
+
+  return true;
+}

package/src/handle-targets/target-object-properties.test.ts

@@ -0,0 +1,140 @@
+import dedent from 'dedent';
+import { describe } from 'vitest';
+import { testFormat } from '../__tests__/utils/test-format';
+
+describe('target-object-properties: validation and bypassing', () => {
+  testFormat(
+    'ignores plain string value (not a CallExpression)',
+    { classNameThreshold: 1 },
+    dedent /* ts */ ` const s = { className: 'flex items-center' }; `,
+    dedent /* ts */ ` const s = { className: 'flex items-center' }; `,
+  );
+
+  testFormat(
+    'ignores unrelated object properties',
+    { classNameThreshold: 1 },
+    dedent /* ts */ `
+      const s = { style: cn('flex items-center'), id: cn('foo bar') };
+    `,
+    dedent /* ts */ `
+      const s = { style: cn('flex items-center'), id: cn('foo bar') };
+    `,
+  );
+
+  testFormat(
+    'ignores CallExpression with callee not in tailwindFunctions',
+    { classNameThreshold: 1, tailwindFunctions: ['cn'] },
+    dedent /* ts */ `
+      const s = { className: otherFn('flex items-center text-sm font-bold') };
+    `,
+    dedent /* ts */ `
+      const s = { className: otherFn('flex items-center text-sm font-bold') };
+    `,
+  );
+});
+
+describe('target-object-properties: key pattern matching', () => {
+  testFormat(
+    'formats wrapperClassName object property',
+    { classNameThreshold: 4 },
+    dedent /* ts */ `
+      const s = {
+        wrapperClassName: cn(
+          'flex items-center justify-center text-sm font-bold bg-white',
+        ),
+      };
+    `,
+    dedent /* ts */ `
+      const s = {
+        wrapperClassName: cn(
+          'flex items-center justify-center',
+          'text-sm font-bold',
+          'bg-white',
+        ),
+      };
+    `,
+  );
+
+  testFormat(
+    'formats wrapperclassName (lowercase c) object property',
+    { classNameThreshold: 4 },
+    dedent /* ts */ `
+      const s = {
+        wrapperclassName: cn(
+          'flex items-center justify-center text-sm font-bold bg-white',
+        ),
+      };
+    `,
+    dedent /* ts */ `
+      const s = {
+        wrapperclassName: cn(
+          'flex items-center justify-center',
+          'text-sm font-bold',
+          'bg-white',
+        ),
+      };
+    `,
+  );
+});
+
+describe('target-object-properties: formatting behavior', () => {
+  testFormat(
+    'regroups static strings when > threshold',
+    { classNameThreshold: 4 },
+    dedent /* ts */ `
+      const s = {
+        className: cn(
+          'flex items-center justify-center text-sm font-bold bg-white',
+        ),
+      };
+    `,
+    dedent /* ts */ `
+      const s = {
+        className: cn(
+          'flex items-center justify-center',
+          'text-sm font-bold',
+          'bg-white',
+        ),
+      };
+    `,
+  );
+
+  testFormat(
+    'merges multiple static args into single string in cn() when <= threshold (never simplifies to StringLiteral)',
+    { classNameThreshold: 5 },
+    dedent /* ts */ ` const s = { className: cn('flex', 'items-center') }; `,
+    dedent /* ts */ ` const s = { className: cn('flex items-center') }; `,
+  );
+
+  testFormat(
+    'moves static args to front and preserves dynamic args at end',
+    { classNameThreshold: 4 },
+    dedent /* ts */ `
+      const s = {
+        className: cn(
+          isActive && 'bg-blue-500',
+          'flex items-center text-sm font-bold bg-white',
+          { 'opacity-50': disabled },
+        ),
+      };
+    `,
+    dedent /* ts */ `
+      const s = {
+        className: cn(
+          'flex items-center',
+          'text-sm font-bold',
+          'bg-white',
+          isActive && 'bg-blue-500',
+          { 'opacity-50': disabled },
+        ),
+      };
+    `,
+  );
+
+  testFormat(
+    'leaves untouched when only dynamic args exist',
+    { classNameThreshold: 4 },
+    dedent /* ts */ ` const s = { className: cn(isActive && 'bg-blue-500') }; `,
+    dedent /* ts */ ` const s = { className: cn(isActive && 'bg-blue-500') }; `,
+  );
+});

package/src/handle-targets/target-object-properties.ts

@@ -0,0 +1,41 @@
+import type { Node } from 'estree-jsx';
+import type { PluginOptions } from '../prettier';
+import {
+  isCallExpression,
+  isClassNameKey,
+  isIdentifier,
+  isStaticProperty,
+} from '../ast';
+import { handleExpressionArray } from '../handle-node/handle-expressions';
+
+/**
+ * Handles Object Property class attributes whose value is a CallExpression
+ * calling a function in `tailwindFunctions` (e.g. `{ className: cn(...) }`).
+ */
+export function handleTargetObjectProperty(
+  node: Node,
+  options: PluginOptions,
+): boolean {
+  // Validate that node is an ObjectProperty with matching className key and tailwind function call value
+  if (
+    !isStaticProperty(node, isClassNameKey) ||
+    !isCallExpression(node.value) ||
+    !isIdentifier(node.value.callee, options.tailwindFunctions)
+  ) {
+    return false;
+  }
+
+  // Process arguments through expression array handler
+  const result = handleExpressionArray(node.value.arguments, options);
+
+  // Update arguments while preserving the CallExpression wrapper
+  if (Array.isArray(result)) {
+    node.value.arguments = result;
+  } else {
+    node.value.arguments = [result];
+  }
+
+  return true;
+}
+
+export const handleTargetObjectProperties = handleTargetObjectProperty;

package/src/index.ts

@@ -0,0 +1,13 @@
+import type { Plugin } from 'prettier';
+import { options } from './options';
+import { printers } from './printers';
+
+export { options } from './options';
+export { printers } from './printers';
+
+const plugin: Plugin = {
+  options,
+  printers,
+};
+
+export default plugin;

package/src/options.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest';
+import { resolveOptions } from './options';
+
+describe('resolveOptions validation', () => {
+  it('resolves valid options correctly', () => {
+    const resolved = resolveOptions({ tailwindFunctions: ['cn', 'clsx'] });
+    expect(resolved.tailwindFunctions).toEqual(['cn', 'clsx']);
+    expect(resolved.classNameThreshold).toBe(10);
+    expect(resolved.modifierThreshold).toBe(2);
+  });
+
+  it('customizes classNameThreshold correctly', () => {
+    const resolved = resolveOptions({ classNameThreshold: 5 });
+    expect(resolved.classNameThreshold).toBe(5);
+    expect(resolved.modifierThreshold).toBe(2);
+    expect(resolved.tailwindFunctions).toEqual(['cn']);
+  });
+
+  it('customizes modifierThreshold correctly', () => {
+    const resolved = resolveOptions({ modifierThreshold: 4 });
+    expect(resolved.modifierThreshold).toBe(4);
+  });
+
+  it('falls back to ["cn"] if tailwindFunctions is empty array or undefined', () => {
+    expect(resolveOptions({ tailwindFunctions: [] }).tailwindFunctions).toEqual(
+      ['cn'],
+    );
+    expect(resolveOptions({}).tailwindFunctions).toEqual(['cn']);
+    expect(resolveOptions(null).tailwindFunctions).toEqual(['cn']);
+  });
+
+  it('throws error if tailwindFunctions contains invalid JS/TS identifier', () => {
+    expect(() => resolveOptions({ tailwindFunctions: ['invalid-fn'] })).toThrow(
+      'Option "tailwindFunctions" contains invalid function name "invalid-fn". Function names must be valid JS/TS identifiers.',
+    );
+    expect(() => resolveOptions({ tailwindFunctions: ['123fn'] })).toThrow(
+      'Option "tailwindFunctions" contains invalid function name "123fn". Function names must be valid JS/TS identifiers.',
+    );
+  });
+
+  it('throws error if tailwindFunctions is not an array', () => {
+    expect(() =>
+      resolveOptions({ tailwindFunctions: 'clsx' as unknown as string[] }),
+    ).toThrow('Option "tailwindFunctions" must be an array of strings.');
+    expect(() =>
+      resolveOptions({ tailwindFunctions: 123 as unknown as string[] }),
+    ).toThrow('Option "tailwindFunctions" must be an array of strings.');
+  });
+
+  it('throws error if classNameThreshold is not a non-negative integer', () => {
+    expect(() => resolveOptions({ classNameThreshold: -1 })).toThrow(
+      'Option "classNameThreshold" must be a non-negative integer.',
+    );
+    expect(() => resolveOptions({ classNameThreshold: 2.5 })).toThrow(
+      'Option "classNameThreshold" must be a non-negative integer.',
+    );
+    expect(() =>
+      resolveOptions({ classNameThreshold: '5' as unknown as number }),
+    ).toThrow('Option "classNameThreshold" must be a non-negative integer.');
+  });
+
+  it('throws error if modifierThreshold is not a non-negative integer', () => {
+    expect(() => resolveOptions({ modifierThreshold: -1 })).toThrow(
+      'Option "modifierThreshold" must be a non-negative integer.',
+    );
+    expect(() => resolveOptions({ modifierThreshold: 1.5 })).toThrow(
+      'Option "modifierThreshold" must be a non-negative integer.',
+    );
+    expect(() =>
+      resolveOptions({ modifierThreshold: '2' as unknown as number }),
+    ).toThrow('Option "modifierThreshold" must be a non-negative integer.');
+  });
+});

package/src/options.ts

@@ -0,0 +1,94 @@
+import type { SupportOption } from 'prettier';
+import type { PluginOptions } from './prettier.d';
+
+/**
+ * Runtime Prettier plugin options configuration.
+ *
+ * NOTE: TypeScript type augmentation for Prettier's `Options` interface is declared in:
+ * @see {@link ./prettier.d.ts}
+ */
+
+export const options = {
+  classNameThreshold: {
+    type: 'int',
+    category: 'Format',
+    default: 10,
+    description:
+      'Threshold of class names (split by whitespace) to trigger wrapping.',
+  },
+  modifierThreshold: {
+    type: 'int',
+    category: 'Format',
+    default: 2,
+    description:
+      'Threshold of modifier classes within a category before splitting into separate lines.',
+  },
+  tailwindFunctions: {
+    type: 'string',
+    array: true,
+    category: 'Format',
+    default: [{ value: ['cn'] }],
+    description:
+      'List of custom function names that contain Tailwind CSS class names.',
+  },
+} satisfies Record<string, SupportOption>;
+
+const JS_IDENTIFIER_REGEX = /^[a-z_$][\w$]*$/i;
+
+/**
+ * Validates and resolves plugin options from Prettier runtime options.
+ */
+export function resolveOptions(opts: unknown): PluginOptions {
+  const rawOptions = (opts ?? {}) as Partial<PluginOptions>;
+
+  let tailwindFunctions = ['cn'];
+  if (rawOptions.tailwindFunctions !== undefined) {
+    if (!Array.isArray(rawOptions.tailwindFunctions)) {
+      throw new TypeError(
+        'Option "tailwindFunctions" must be an array of strings.',
+      );
+    }
+    if (rawOptions.tailwindFunctions.length > 0) {
+      tailwindFunctions = rawOptions.tailwindFunctions;
+    }
+  }
+
+  for (const fnName of tailwindFunctions) {
+    if (typeof fnName !== 'string' || !JS_IDENTIFIER_REGEX.test(fnName)) {
+      throw new Error(
+        `Option "tailwindFunctions" contains invalid function name "${fnName}". Function names must be valid JS/TS identifiers.`,
+      );
+    }
+  }
+
+  if (rawOptions.classNameThreshold !== undefined) {
+    if (
+      typeof rawOptions.classNameThreshold !== 'number' ||
+      !Number.isInteger(rawOptions.classNameThreshold) ||
+      rawOptions.classNameThreshold < 0
+    ) {
+      throw new Error(
+        'Option "classNameThreshold" must be a non-negative integer.',
+      );
+    }
+  }
+
+  if (rawOptions.modifierThreshold !== undefined) {
+    if (
+      typeof rawOptions.modifierThreshold !== 'number' ||
+      !Number.isInteger(rawOptions.modifierThreshold) ||
+      rawOptions.modifierThreshold < 0
+    ) {
+      throw new Error(
+        'Option "modifierThreshold" must be a non-negative integer.',
+      );
+    }
+  }
+
+  return {
+    classNameThreshold: rawOptions.classNameThreshold ?? 10,
+    modifierThreshold: rawOptions.modifierThreshold ?? 2,
+    ...rawOptions,
+    tailwindFunctions,
+  } as PluginOptions;
+}