@culur/prettier-plugin-tailwindcss-group 1.1.0

package/src/ast/ast-jsx.ts

@@ -0,0 +1,53 @@
+import type {
+  CallExpression,
+  Expression,
+  Identifier,
+  JSXAttribute,
+  JSXEmptyExpression,
+  JSXExpressionContainer,
+  JSXIdentifier,
+  Node,
+} from 'estree-jsx';
+
+export function isJSXAttribute(node: Node): node is JSXAttribute {
+  return node.type === 'JSXAttribute';
+}
+
+export function isJSXIdentifier(
+  node: Node,
+  name?: string,
+): node is JSXIdentifier {
+  if (node.type !== 'JSXIdentifier') return false;
+  if (name !== undefined && node.name !== name) return false;
+  return true;
+}
+
+export function isJSXExpressionContainer(
+  node: Node,
+): node is JSXExpressionContainer {
+  return node.type === 'JSXExpressionContainer';
+}
+
+export function buildExpressionContainer(
+  expression: Expression | JSXEmptyExpression,
+): JSXExpressionContainer {
+  return {
+    type: 'JSXExpressionContainer',
+    expression,
+  } satisfies JSXExpressionContainer;
+}
+
+export function buildCallExpression(
+  wrapperName: string,
+  args: Expression[],
+): CallExpression {
+  return {
+    type: 'CallExpression',
+    callee: {
+      type: 'Identifier',
+      name: wrapperName,
+    } satisfies Identifier,
+    arguments: args,
+    optional: false,
+  } satisfies CallExpression;
+}

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

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import { parseExpression } from '../__tests__/utils/ast-estree';
+import { buildStringLiteral, isLiteral, isStringLiteral } from './ast-literal';
+
+describe('literal utils', () => {
+  describe('isLiteral', () => {
+    it('returns true for Literal nodes', () => {
+      const nodeStr = parseExpression('"test"');
+      const nodeNum = parseExpression('123');
+      expect(isLiteral(nodeStr)).toBe(true);
+      expect(isLiteral(nodeNum)).toBe(true);
+    });
+
+    it('returns false for non-Literal nodes', () => {
+      const node = parseExpression('foo');
+      expect(isLiteral(node)).toBe(false);
+      expect(isLiteral(null)).toBe(false);
+      expect(isLiteral(undefined)).toBe(false);
+    });
+  });
+
+  describe('isStringLiteral', () => {
+    it('returns true for StringLiteral nodes', () => {
+      const node = parseExpression('"test"');
+      expect(isStringLiteral(node)).toBe(true);
+    });
+
+    it('returns false for non-string literals or non-literals', () => {
+      const nodeNum = parseExpression('123');
+      const nodeIdent = parseExpression('foo');
+      expect(isStringLiteral(nodeNum)).toBe(false);
+      expect(isStringLiteral(nodeIdent)).toBe(false);
+      expect(isStringLiteral(null)).toBe(false);
+      expect(isStringLiteral(undefined)).toBe(false);
+    });
+  });
+
+  describe('buildStringLiteral', () => {
+    it('creates a StringLiteral with value and JSON raw', () => {
+      expect(buildStringLiteral('btn primary')).toEqual({
+        type: 'Literal',
+        value: 'btn primary',
+        raw: JSON.stringify('btn primary'),
+      });
+    });
+  });
+});

package/src/ast/ast-literal.ts

@@ -0,0 +1,17 @@
+import type { Literal, Node, SimpleLiteral } from 'estree-jsx';
+
+export function isLiteral(node?: Node | null): node is Literal {
+  return Boolean(node && node.type === 'Literal');
+}
+
+export type StringLiteral = SimpleLiteral & { value: string };
+
+export function isStringLiteral(node?: Node | null): node is StringLiteral {
+  return isLiteral(node) && typeof node.value === 'string';
+}
+
+export const buildStringLiteral = (value: string): StringLiteral => ({
+  type: 'Literal',
+  value,
+  raw: JSON.stringify(value),
+});

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

@@ -0,0 +1,96 @@
+import type { ObjectExpression } from 'estree-jsx';
+import { assert, describe, expect, it } from 'vitest';
+import { parseExpression } from '../__tests__/utils/ast-estree';
+import {
+  isObjectExpression,
+  isProperty,
+  isStaticProperty,
+} from './ast-property';
+import { isClassNameKey } from './key';
+
+describe('ast-property utils', () => {
+  describe('isObjectExpression', () => {
+    it('returns true for ObjectExpression nodes', () => {
+      const node = parseExpression('{ className: "flex" }');
+      expect(isObjectExpression(node)).toBe(true);
+    });
+
+    it('returns false for other node types', () => {
+      const node = parseExpression('foo');
+      expect(isObjectExpression(node)).toBe(false);
+    });
+  });
+
+  describe('isProperty', () => {
+    it('returns true for Property nodes', () => {
+      const node = parseExpression(`{ className: "flex" }`);
+      assert(isObjectExpression(node));
+      expect(isProperty(node.properties[0])).toBe(true);
+    });
+
+    it('returns false for non-Property nodes', () => {
+      const node = parseExpression('foo');
+      expect(isProperty(node)).toBe(false);
+    });
+  });
+
+  describe('isStaticProperty', () => {
+    it('returns true for non-computed Identifier or Literal keys without key filter', () => {
+      const objIdent = parseExpression<ObjectExpression>(
+        '{ className: "flex" }',
+      );
+      const objStr = parseExpression<ObjectExpression>(
+        '{ "className": "flex" }',
+      );
+      const objNum = parseExpression<ObjectExpression>('{ 123: "flex" }');
+
+      expect(isStaticProperty(objIdent.properties[0])).toBe(true);
+      expect(isStaticProperty(objStr.properties[0])).toBe(true);
+      expect(isStaticProperty(objNum.properties[0])).toBe(true);
+    });
+
+    it('filters by string keyName', () => {
+      const objVariants = parseExpression<ObjectExpression>('{ variants: {} }');
+      const objNum = parseExpression<ObjectExpression>('{ 123: "flex" }');
+
+      expect(isStaticProperty(objVariants.properties[0], 'variants')).toBe(
+        true,
+      );
+      expect(
+        isStaticProperty(objVariants.properties[0], 'compoundVariants'),
+      ).toBe(false);
+      expect(isStaticProperty(objNum.properties[0], 'variants')).toBe(false);
+    });
+
+    it('filters by callback keyName', () => {
+      const objWrapper = parseExpression<ObjectExpression>(
+        '{ wrapperClassName: "flex" }',
+      );
+      const objStyle = parseExpression<ObjectExpression>('{ style: "flex" }');
+      const objNum = parseExpression<ObjectExpression>('{ 123: "flex" }');
+
+      expect(isStaticProperty(objWrapper.properties[0], isClassNameKey)).toBe(
+        true,
+      );
+      expect(isStaticProperty(objStyle.properties[0], isClassNameKey)).toBe(
+        false,
+      );
+      expect(isStaticProperty(objNum.properties[0], isClassNameKey)).toBe(
+        false,
+      );
+    });
+
+    it('returns false for computed or non-static keys', () => {
+      const objComputed = parseExpression<ObjectExpression>(
+        '{ [className]: "flex" }',
+      );
+      const nodeIdent = parseExpression('foo');
+
+      expect(isStaticProperty(objComputed.properties[0])).toBe(false);
+      expect(isStaticProperty(objComputed.properties[0], 'className')).toBe(
+        false,
+      );
+      expect(isStaticProperty(nodeIdent)).toBe(false);
+    });
+  });
+});

package/src/ast/ast-property.ts

@@ -0,0 +1,32 @@
+import type { Node, ObjectExpression, Property } from 'estree-jsx';
+import { isIdentifier } from './ast-common';
+import { isLiteral, isStringLiteral } from './ast-literal';
+
+export function isObjectExpression(node: Node): node is ObjectExpression {
+  return node.type === 'ObjectExpression';
+}
+
+export function isProperty(node: Node): node is Property {
+  return node.type === 'Property';
+}
+
+export function isStaticProperty(
+  node: Node,
+  keyName?: string | ((key: string) => boolean),
+): node is Property {
+  if (!isProperty(node) || node.computed) return false;
+
+  const key = isIdentifier(node.key)
+    ? node.key.name
+    : isStringLiteral(node.key)
+      ? node.key.value
+      : null;
+
+  if (key === null) {
+    return keyName === undefined && isLiteral(node.key);
+  }
+
+  if (keyName === undefined) return true;
+  if (typeof keyName === 'function') return keyName(key);
+  return key === keyName;
+}

package/src/ast/index.ts

@@ -0,0 +1,8 @@
+export * from './ast-array-expression';
+export * from './ast-call-expression';
+export * from './ast-comment';
+export * from './ast-common';
+export * from './ast-jsx';
+export * from './ast-literal';
+export * from './ast-property';
+export * from './key';

package/src/ast/key.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { isClassNameKey } from './key';
+
+describe('isClassNameKeyName', () => {
+  it('matches exact className, suffix ClassName, and suffix className', () => {
+    expect(isClassNameKey('className')).toBe(true);
+    expect(isClassNameKey('wrapperClassName')).toBe(true);
+    expect(isClassNameKey('wrapperclassName')).toBe(true);
+    expect(isClassNameKey('containerClassName')).toBe(true);
+    expect(isClassNameKey('$prefixClassName')).toBe(true);
+    expect(isClassNameKey('_privateClassName')).toBe(true);
+  });
+
+  it('rejects names that do not match', () => {
+    expect(isClassNameKey('classname')).toBe(false);
+    expect(isClassNameKey('CLASSNAME')).toBe(false);
+    expect(isClassNameKey('id')).toBe(false);
+    expect(isClassNameKey('style')).toBe(false);
+    expect(isClassNameKey('')).toBe(false);
+  });
+});

package/src/ast/key.ts

@@ -0,0 +1,4 @@
+export const isClassNameKey = (
+  keyName: string,
+): keyName is `${string}ClassName` | `${string}className` =>
+  keyName.endsWith('ClassName') || keyName.endsWith('className');

package/src/group-classes/group-classes.bucket.ts

@@ -0,0 +1,61 @@
+import type { ClassGroupBucket } from './group-classes.types';
+import { classGroups, classGroupsCount } from '../orders/class-groups';
+import { configUtils } from '../orders/class-order.tailwind-merge';
+
+/**
+ * Fast lookup map from tailwind-merge groupId to class group index (0-based).
+ * Built with null prototype to avoid prototype pollution and enable O(1) lookups.
+ */
+const groupIdToGroupIndex: Record<string, number> = Object.create(null);
+
+for (let groupIndex = 0; groupIndex < classGroups.length; groupIndex++) {
+  const groupList = classGroups[groupIndex];
+  for (let i = 0; i < groupList.length; i++) {
+    groupIdToGroupIndex[groupList[i]] = groupIndex;
+  }
+}
+
+export function createClassBuckets(): ClassGroupBucket[] {
+  return Array.from({ length: classGroupsCount }, () => ({
+    baseClasses: [],
+    modifierGroups: new Map(),
+    totalModifierCount: 0,
+  }));
+}
+
+export function resolveGroupIndex(
+  parsed: ReturnType<typeof configUtils.parseClassName>,
+  unknownGroupIndex: number,
+): number {
+  // Strip postfix modifier (e.g. '/item' or '/50') to properly resolve base class groupId
+  const baseClassName = parsed.maybePostfixModifierPosition
+    ? parsed.baseClassName.slice(0, parsed.maybePostfixModifierPosition)
+    : parsed.baseClassName;
+
+  const groupId = configUtils.getClassGroupId(baseClassName);
+
+  return groupId !== undefined && groupIdToGroupIndex[groupId] !== undefined
+    ? groupIdToGroupIndex[groupId]
+    : unknownGroupIndex;
+}
+
+export function addClassToBucket(
+  bucket: ClassGroupBucket,
+  cls: string,
+  modifiers: string[],
+): void {
+  if (modifiers.length === 0) {
+    bucket.baseClasses.push(cls);
+    return;
+  }
+
+  const modifierKey = modifiers.join(':');
+  const group = bucket.modifierGroups.get(modifierKey);
+
+  if (group) {
+    group.push(cls);
+  } else {
+    bucket.modifierGroups.set(modifierKey, [cls]);
+  }
+  bucket.totalModifierCount++;
+}

package/src/group-classes/group-classes.format.ts

@@ -0,0 +1,39 @@
+import type { ClassGroupBucket } from './group-classes.types';
+import { sortModifierKeys } from '../orders/modifier-order.prettier-plugin-tailwindcss';
+
+export function formatBucketLines(
+  bucket: ClassGroupBucket,
+  modifierThreshold: number,
+): string[] {
+  const { baseClasses, modifierGroups, totalModifierCount } = bucket;
+
+  if (baseClasses.length === 0 && totalModifierCount === 0) {
+    return [];
+  }
+
+  const sortedModifierKeys = sortModifierKeys(
+    Array.from(modifierGroups.keys()),
+  );
+
+  if (totalModifierCount <= modifierThreshold) {
+    // Threshold not met (<= modifierThreshold): Merge all classes into 1 line
+    const lineClasses = [...baseClasses];
+    for (let i = 0; i < sortedModifierKeys.length; i++) {
+      lineClasses.push(...modifierGroups.get(sortedModifierKeys[i])!);
+    }
+    return [lineClasses.join(' ')];
+  }
+
+  // Threshold exceeded (> modifierThreshold): Separate base classes and each modifier cluster into distinct lines
+  const lines: string[] = [];
+  if (baseClasses.length > 0) {
+    lines.push(baseClasses.join(' '));
+  }
+
+  for (let i = 0; i < sortedModifierKeys.length; i++) {
+    const modClasses = modifierGroups.get(sortedModifierKeys[i])!;
+    lines.push(modClasses.join(' '));
+  }
+
+  return lines;
+}

package/src/group-classes/group-classes.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, it } from 'vitest';
+import { groupClasses } from './group-classes';
+
+describe('groupClasses with category-first and modifier threshold', () => {
+  it('should group classes without modifiers according to categories', () => {
+    const input = ['flex', 'items-center', 'p-4', 'text-sm', 'bg-white'];
+    const result = groupClasses(input);
+
+    expect(result).toEqual([
+      'flex items-center',
+      'p-4',
+      'text-sm',
+      'bg-white',
+    ]);
+  });
+
+  it('should merge modifier classes into the base class line when modifier count <= 2 (threshold)', () => {
+    const input = [
+      'text-sm',
+      'font-medium',
+      'hover:text-blue-600',
+      'dark:text-white',
+    ];
+    const result = groupClasses(input);
+
+    expect(result).toEqual([
+      'text-sm font-medium hover:text-blue-600 dark:text-white',
+    ]);
+  });
+
+  it('should split modifier classes into separate lines when total modifier count >= 3', () => {
+    const input = [
+      'bg-white',
+      'hover:bg-gray-100',
+      'dark:bg-gray-900',
+      'dark:hover:bg-gray-800',
+      'md:bg-transparent',
+    ];
+    const result = groupClasses(input);
+
+    expect(result).toEqual([
+      'bg-white',
+      'hover:bg-gray-100',
+      'md:bg-transparent',
+      'dark:bg-gray-900',
+      'dark:hover:bg-gray-800',
+    ]);
+  });
+
+  it('should respect custom modifierThreshold option', () => {
+    const input = [
+      'bg-white',
+      'hover:bg-gray-100',
+      'dark:bg-gray-900',
+      'dark:hover:bg-gray-800',
+    ];
+
+    // With modifierThreshold = 4, 3 modifiers should remain merged
+    const mergedResult = groupClasses(input, 4);
+    expect(mergedResult).toEqual([
+      'bg-white hover:bg-gray-100 dark:bg-gray-900 dark:hover:bg-gray-800',
+    ]);
+
+    // With modifierThreshold = 1, 3 modifiers should split
+    const splitResult = groupClasses(input, 1);
+    expect(splitResult).toEqual([
+      'bg-white',
+      'hover:bg-gray-100',
+      'dark:bg-gray-900',
+      'dark:hover:bg-gray-800',
+    ]);
+
+    // With modifierThreshold = 0, even a single modifier splits from base classes
+    const zeroResult = groupClasses(['flex', 'hover:flex'], 0);
+    expect(zeroResult).toEqual(['flex', 'hover:flex']);
+  });
+
+  it('should handle postfix opacity modifier such as /50 and group by base class category', () => {
+    const input = ['bg-red-500/50', 'bg-white', 'text-white/80', 'text-sm'];
+    const result = groupClasses(input);
+
+    expect(result).toEqual([
+      'text-white/80 text-sm',
+      'bg-red-500/50 bg-white',
+    ]);
+  });
+
+  it('should handle category without base classes when total modifiers >= 3', () => {
+    const input = [
+      'focus:ring-2',
+      'focus:ring-blue-500',
+      'dark:focus:ring-blue-400',
+    ];
+    const result = groupClasses(input);
+
+    expect(result).toEqual([
+      'focus:ring-2 focus:ring-blue-500',
+      'dark:focus:ring-blue-400',
+    ]);
+  });
+
+  it('should handle named group, peer and container classes in category 1', () => {
+    const input = [
+      'group/button',
+      'peer/draft',
+      '@container/sidebar',
+      'text-sm',
+    ];
+    const result = groupClasses(input);
+
+    expect(result).toEqual([
+      'group/button peer/draft @container/sidebar',
+      'text-sm',
+    ]);
+  });
+
+  it('should handle unknown custom classes and put them at the end', () => {
+    const input = ['flex', 'custom-component-class', 'another-unknown'];
+    const result = groupClasses(input);
+
+    expect(result).toEqual([
+      'flex',
+      'custom-component-class another-unknown',
+    ]);
+  });
+});

package/src/group-classes/group-classes.ts

@@ -0,0 +1,34 @@
+import { classGroupsCount } from '../orders/class-groups';
+import { configUtils } from '../orders/class-order.tailwind-merge';
+import {
+  addClassToBucket,
+  createClassBuckets,
+  resolveGroupIndex,
+} from './group-classes.bucket';
+import { formatBucketLines } from './group-classes.format';
+
+export function groupClasses(
+  classes: string[],
+  modifierThreshold = 2,
+): string[] {
+  const unknownGroupIndex = classGroupsCount - 1;
+  const buckets = createClassBuckets();
+
+  for (let i = 0; i < classes.length; i++) {
+    const cls = classes[i];
+    const parsed = configUtils.parseClassName(cls);
+    const groupIndex = resolveGroupIndex(parsed, unknownGroupIndex);
+    addClassToBucket(buckets[groupIndex], cls, parsed.modifiers);
+  }
+
+  const result: string[] = [];
+
+  for (let i = 0; i < classGroupsCount; i++) {
+    const lines = formatBucketLines(buckets[i], modifierThreshold);
+    for (let j = 0; j < lines.length; j++) {
+      result.push(lines[j]);
+    }
+  }
+
+  return result;
+}

package/src/group-classes/group-classes.types.ts

@@ -0,0 +1,5 @@
+export interface ClassGroupBucket {
+  baseClasses: string[];
+  modifierGroups: Map<string, string[]>;
+  totalModifierCount: number;
+}

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

@@ -0,0 +1,133 @@
+import dedent from 'dedent';
+import { describe } from 'vitest';
+import { testFormat } from '../__tests__/utils/test-format';
+
+describe('handle-cva-class-value: case 1: stringLiteral expression', () => {
+  testFormat(
+    'converts StringLiteral 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(
+    'leaves StringLiteral unchanged when class count <= threshold',
+    { classNameThreshold: 5 },
+    dedent /* ts */ ` const b = cva('flex items-center text-sm'); `,
+    dedent /* ts */ ` const b = cva('flex items-center text-sm'); `,
+  );
+});
+
+describe('handle-cva-class-value: case 2: callExpression with tailwind function', () => {
+  testFormat(
+    'simplifies CallExpression to StringLiteral when class count <= threshold',
+    { classNameThreshold: 5 },
+    dedent /* ts */ ` const b = cva(cn('flex', 'items-center')); `,
+    dedent /* ts */ ` const b = cva('flex items-center'); `,
+  );
+
+  testFormat(
+    'groups CallExpression 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(
+    'supports custom tailwindFunctions option',
+    { classNameThreshold: 2, tailwindFunctions: ['clsx'] },
+    dedent /* ts */ `
+      const b = cva(clsx('flex items-center text-sm font-bold'));
+    `,
+    dedent /* ts */ `
+      const b = cva(clsx('flex items-center', 'text-sm font-bold'));
+    `,
+  );
+});
+
+describe('handle-cva-class-value: case 3: arrayExpression', () => {
+  testFormat(
+    'simplifies ArrayExpression to StringLiteral when class count <= threshold',
+    { classNameThreshold: 10 },
+    dedent /* ts */ ` const b = cva(['flex', 'items-center', 'text-sm']); `,
+    dedent /* ts */ ` const b = cva('flex items-center text-sm'); `,
+  );
+
+  testFormat(
+    'flattens and regroups ArrayExpression 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(
+    'preserves dynamic elements within ArrayExpression',
+    { classNameThreshold: 1 },
+    dedent /* ts */ ` const b = cva([isActive && 'bg-blue-500', 'flex']); `,
+    dedent /* ts */ ` const b = cva(['flex', isActive && 'bg-blue-500']); `,
+  );
+
+  testFormat(
+    'preserves sparse array holes (empty slots) when regrouping',
+    { 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-cva-class-value: fallback: unrecognized or other expressions', () => {
+  testFormat(
+    'ignores CallExpression with callee not in tailwindFunctions',
+    { classNameThreshold: 1, tailwindFunctions: ['cn'] },
+    dedent /* ts */ ` const b = cva(customHelper('flex items-center')); `,
+    dedent /* ts */ ` const b = cva(customHelper('flex items-center')); `,
+  );
+
+  testFormat(
+    'ignores Identifier class value',
+    { classNameThreshold: 1 },
+    dedent /* ts */ ` const b = cva(baseStyles); `,
+    dedent /* ts */ ` const b = cva(baseStyles); `,
+  );
+});