@culur/prettier-plugin-tailwindcss-group 1.1.0

package/src/orders/class-groups.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'vitest';
+import { classGroups, classGroupsCount } from './class-groups';
+import { config } from './class-order.tailwind-merge';
+
+describe('classGroups validation', () => {
+  const tailwindGroupIds = Object.keys(config.classGroups);
+
+  it('should match classGroupsCount with classGroups length + 1', () => {
+    expect(classGroupsCount).toBe(classGroups.length + 1);
+  });
+
+  it('should not contain any duplicate groupIds across class groups', () => {
+    const seen = new Set<string>();
+    const duplicates: string[] = [];
+
+    for (const groupList of classGroups) {
+      for (const id of groupList) {
+        if (seen.has(id)) {
+          duplicates.push(id);
+        }
+        seen.add(id);
+      }
+    }
+
+    expect(
+      duplicates,
+      `Found duplicate groupIds: ${duplicates.join(', ')}`,
+    ).toEqual([]);
+  });
+
+  it('should not contain any extraneous groupIds not present in tailwind-merge', () => {
+    const validGroupIdsSet = new Set(tailwindGroupIds);
+    const extraGroupIds: string[] = [];
+
+    for (const groupList of classGroups) {
+      for (const id of groupList) {
+        if (!validGroupIdsSet.has(id)) {
+          extraGroupIds.push(id);
+        }
+      }
+    }
+
+    expect(
+      extraGroupIds,
+      `Found extraneous groupIds not in tailwind-merge: ${extraGroupIds.join(', ')}`,
+    ).toEqual([]);
+  });
+
+  it('should not omit any groupIds defined in tailwind-merge', () => {
+    const declaredGroupIdsSet = new Set<string>();
+    for (const groupList of classGroups) {
+      for (const id of groupList) {
+        declaredGroupIdsSet.add(id);
+      }
+    }
+
+    const missingGroupIds = tailwindGroupIds.filter(
+      id => !declaredGroupIdsSet.has(id),
+    );
+
+    expect(
+      missingGroupIds,
+      `Missing the following groupIds from tailwind-merge: ${missingGroupIds.join(', ')}`,
+    ).toEqual([]);
+  });
+
+  it('should have the exact total declared count equal to tailwind-merge classGroups count', () => {
+    const totalDeclared = classGroups.reduce(
+      (sum, groupList) => sum + groupList.length,
+      0,
+    );
+    expect(totalDeclared).toBe(tailwindGroupIds.length);
+  });
+});

package/src/orders/class-groups.ts

@@ -0,0 +1,178 @@
+/**
+ * Groups Tailwind CSS classGroupIds into 14 primary categories (+ 1 unknown group) for the plugin.
+ * Each category contains a list of corresponding groupIds from tailwind-merge.
+ */
+export const classGroups: readonly (readonly string[])[] = [
+  //! Context & Container
+  // prettier-multiline-arrays-next-line-pattern: 4
+  [
+    'group', 'peer', 'container-type', 'container-named',
+  ],
+
+  //! Positioning
+  // prettier-multiline-arrays-next-line-pattern: 1 7 4 3
+  [
+    'position', // position
+    'inset', 'inset-x', 'inset-y', 'start', 'end', 'inset-bs', 'inset-be', // inset
+    'top', 'right', 'bottom', 'left', // top, right, bottom, left
+    'float', 'clear', 'z', // float, clear, z-index
+  ],
+
+  //! Display, Flex, Grid
+  // prettier-multiline-arrays-next-line-pattern: 4 7 4 4 3 3 3 3 3 1
+  [
+    'display', 'sr', 'isolation', 'visibility', // display & visibility
+    'flex-direction', 'flex-wrap', 'flex', 'grow', 'shrink', 'basis', 'order', // flex
+    'grid-cols', 'col-start-end', 'col-start', 'col-end', // grid column
+    'grid-rows', 'row-start-end', 'row-start', 'row-end', // grid row
+    'grid-flow', 'auto-cols', 'auto-rows', // grid flow
+    'gap', 'gap-x', 'gap-y', // gap
+    'justify-content', 'justify-items', 'justify-self', // justify
+    'align-content', 'align-items', 'align-self', // align
+    'place-content', 'place-items', 'place-self', // place
+    'columns', // columns
+  ],
+
+  //! Box Model & Spacing
+  // prettier-multiline-arrays-next-line-pattern: 8 3 3 1 1 3 11 11 4
+  [
+    'w', 'min-w', 'max-w', 'h', 'min-h', 'max-h', 'size', 'aspect', // size
+    'inline-size', 'min-inline-size', 'max-inline-size', // inline-size
+    'block-size', 'min-block-size', 'max-block-size', // block-size
+    'box', // box-sizing
+    'container', // container
+    'break-after', 'break-before', 'break-inside', // break
+    'p', 'px', 'py', 'ps', 'pe', 'pbs', 'pbe', 'pt', 'pr', 'pb', 'pl', // padding
+    'm', 'mx', 'my', 'ms', 'me', 'mbs', 'mbe', 'mt', 'mr', 'mb', 'ml', // margin
+    'space-x', 'space-x-reverse', 'space-y', 'space-y-reverse', // space
+  ],
+
+  //! Overflow & Scroll
+  // prettier-multiline-arrays-next-line-pattern: 6 1 4 11 11
+  [
+    'overflow', 'overflow-x', 'overflow-y', 'overscroll', 'overscroll-x', 'overscroll-y', // overflow
+    'scroll-behavior', // scroll-behavior
+    'scrollbar-thumb-color', 'scrollbar-track-color', 'scrollbar-gutter', 'scrollbar-w', // scrollbar
+    'scroll-m', 'scroll-mx', 'scroll-my', 'scroll-ms', 'scroll-me', 'scroll-mbs', 'scroll-mbe', 'scroll-mt', 'scroll-mr', 'scroll-mb', 'scroll-ml', // scroll margin
+    'scroll-p', 'scroll-px', 'scroll-py', 'scroll-ps', 'scroll-pe', 'scroll-pbs', 'scroll-pbe', 'scroll-pt', 'scroll-pr', 'scroll-pb', 'scroll-pl', // scroll padding
+  ],
+
+  //! Typography
+  // prettier-multiline-arrays-next-line-pattern: 7 6 3 2 2 5 7 3 2 2 1
+  [
+    'font-size', 'font-smoothing', 'font-style', 'font-weight', 'font-stretch', 'font-family', 'font-features', // font
+    'fvn-normal', 'fvn-ordinal', 'fvn-slashed-zero', 'fvn-figure', 'fvn-spacing', 'fvn-fraction', // font-variant-numeric
+    'list-image', 'list-style-position', 'list-style-type', // list
+    'placeholder-color', 'text-color', // color
+    'text-shadow', 'text-shadow-color', // text-shadow
+    'text-decoration', 'text-decoration-style', 'text-decoration-thickness', 'text-decoration-color', 'underline-offset', // underline
+    'line-clamp', 'text-overflow', 'text-wrap', 'whitespace', 'break', 'wrap', 'hyphens', // text wrap
+    'tracking', 'leading', 'text-transform', // transform
+    'indent', 'tab-size', // indent
+    'vertical-align', 'text-alignment', // align
+    'content', // content
+  ],
+
+  //! Background
+  // prettier-multiline-arrays-next-line-pattern: 8 6 1 2
+  [
+    'bg-attachment', 'bg-clip', 'bg-origin', 'bg-position', 'bg-repeat', 'bg-size', 'bg-image', 'bg-color', // background
+    'gradient-from-pos', 'gradient-via-pos', 'gradient-to-pos', 'gradient-from', 'gradient-via', 'gradient-to', // gradient
+    'box-decoration', // box-decoration
+    'object-fit', 'object-position', // object (image)
+  ],
+
+  //! Filter
+  // prettier-multiline-arrays-next-line-pattern: 11 10
+  [
+    'filter', 'blur', 'brightness', 'contrast', 'drop-shadow', 'drop-shadow-color', 'grayscale', 'hue-rotate', 'invert', 'saturate', 'sepia', // filter
+    'backdrop-filter', 'backdrop-blur', 'backdrop-brightness', 'backdrop-contrast', 'backdrop-grayscale', 'backdrop-hue-rotate', 'backdrop-invert', 'backdrop-opacity', 'backdrop-saturate', 'backdrop-sepia', // backdrop-filter
+  ],
+
+  //! Border & Shadow
+  // prettier-multiline-arrays-next-line-pattern: 3 4 4 1 3 4 4 4 2 3 4 4 4 4 2 2 5 2 2
+  [
+    'border-w', 'border-w-x', 'border-w-y', // border width
+    'border-w-s', 'border-w-e', 'border-w-bs', 'border-w-be',
+    'border-w-t', 'border-w-r', 'border-w-b', 'border-w-l',
+
+    'border-style',
+    'border-color', 'border-color-x', 'border-color-y', // border color
+    'border-color-s', 'border-color-e', 'border-color-bs', 'border-color-be',
+    'border-color-t', 'border-color-r', 'border-color-b', 'border-color-l',
+
+    'divide-x', 'divide-x-reverse', 'divide-y', 'divide-y-reverse', // divide
+    'divide-style', 'divide-color', // divide style & divide color
+
+    'rounded', 'rounded-s', 'rounded-e', // rounded
+    'rounded-t', 'rounded-r', 'rounded-b', 'rounded-l',
+    'rounded-ss', 'rounded-se', 'rounded-ee', 'rounded-es',
+    'rounded-tl', 'rounded-tr', 'rounded-br', 'rounded-bl',
+
+    'outline-style', 'outline-offset', 'outline-w', 'outline-color', // outline
+
+    'shadow', 'shadow-color', // shadow
+    'inset-shadow', 'inset-shadow-color', // inset-shadow
+    'ring-w', 'ring-w-inset', 'ring-color', 'ring-offset-w', 'ring-offset-color', // ring
+    'inset-ring-w', 'inset-ring-color', // inset-ring
+  ],
+
+  //! Effect & Mask
+  // prettier-multiline-arrays-next-line-pattern: 3 2 5 4 4 4 4 4 4 5 3 5 7
+  [
+    'opacity', 'mix-blend', 'bg-blend',
+    'mask-clip', 'mask-composite',
+    'mask-image-linear-pos', 'mask-image-linear-from-pos', 'mask-image-linear-to-pos', 'mask-image-linear-from-color', 'mask-image-linear-to-color', // mask-image-linear
+    'mask-image-t-from-pos', 'mask-image-t-to-pos', 'mask-image-t-from-color', 'mask-image-t-to-color', // mask-image-t
+    'mask-image-r-from-pos', 'mask-image-r-to-pos', 'mask-image-r-from-color', 'mask-image-r-to-color', // mask-image-r
+    'mask-image-b-from-pos', 'mask-image-b-to-pos', 'mask-image-b-from-color', 'mask-image-b-to-color', // mask-image-b
+    'mask-image-l-from-pos', 'mask-image-l-to-pos', 'mask-image-l-from-color', 'mask-image-l-to-color', // mask-image-l
+    'mask-image-x-from-pos', 'mask-image-x-to-pos', 'mask-image-x-from-color', 'mask-image-x-to-color', // mask-image-x
+    'mask-image-y-from-pos', 'mask-image-y-to-pos', 'mask-image-y-from-color', 'mask-image-y-to-color', // mask-image-y
+
+    'mask-image-radial', 'mask-image-radial-from-pos', 'mask-image-radial-to-pos', 'mask-image-radial-from-color', 'mask-image-radial-to-color', // mask-image-radial
+    'mask-image-radial-shape', 'mask-image-radial-size', 'mask-image-radial-pos', // mask-image-radial
+    'mask-image-conic-pos', 'mask-image-conic-from-pos', 'mask-image-conic-to-pos', 'mask-image-conic-from-color', 'mask-image-conic-to-color', // mask-image-conic
+    'mask-mode', 'mask-origin', 'mask-position', 'mask-repeat', 'mask-size', 'mask-type', 'mask-image', // mask others
+  ],
+
+  //! Table
+  // prettier-multiline-arrays-next-line-pattern: 6
+  [
+    'border-collapse', 'border-spacing', 'border-spacing-x', 'border-spacing-y', 'table-layout', 'caption',
+  ],
+
+  //! Transition & Transform
+  // prettier-multiline-arrays-next-line-pattern: 5 4 4 5 3 8 1
+  [
+    'transition', 'transition-behavior', 'duration', 'ease', 'delay', // transition & animation
+    'animate', 'backface', 'perspective', 'perspective-origin', // transforms
+    'rotate', 'rotate-x', 'rotate-y', 'rotate-z', // rotate
+    'scale', 'scale-x', 'scale-y', 'scale-z', 'scale-3d', // scale
+    'skew', 'skew-x', 'skew-y', // skew
+    'transform', 'transform-origin', 'transform-style', 'translate', 'translate-x', 'translate-y', 'translate-z', 'translate-none', // transform
+    'zoom', // zoom
+  ],
+
+  //! Interactivity
+  // prettier-multiline-arrays-next-line-pattern: 4 3 2 4 4 2
+  [
+    'accent', 'forced-color-adjust', 'appearance', 'color-scheme',
+    'caret-color', 'cursor', 'pointer-events', // caret & cursor
+    'field-sizing', 'resize', // resize
+    'snap-align', 'snap-stop', 'snap-type', 'snap-strictness', // snap
+    'touch', 'touch-x', 'touch-y', 'touch-pz', // touch
+    'select', 'will-change', //
+  ],
+
+  //! SVG
+  // prettier-multiline-arrays-next-line-pattern: 3
+  [
+    'fill', 'stroke-w', 'stroke',
+  ],
+];
+
+/**
+ * Total class group count (14 standard groups + 1 Unknown/Custom group at the end).
+ */
+export const classGroupsCount = classGroups.length + 1;

package/src/orders/class-order.tailwind-merge.ts

@@ -0,0 +1,26 @@
+import type { ConfigExtension } from 'tailwind-merge-ts';
+import type { AnyThemeGroupIds } from 'tailwind-merge-ts/lib/types';
+import { getDefaultConfig, mergeConfigs } from 'tailwind-merge-ts';
+import { createConfigUtils } from 'tailwind-merge-ts/lib/config-utils';
+
+type ExtendedGroups = 'group' | 'peer';
+
+const isGroupNamed = (value: string) => value.startsWith('group/');
+const isPeerNamed = (value: string) => value.startsWith('peer/');
+
+const configExtend: ConfigExtension<
+  ExtendedGroups,
+  AnyThemeGroupIds
+>['extend'] = {
+  classGroups: {
+    group: ['group', isGroupNamed],
+    peer: ['peer', isPeerNamed],
+  },
+};
+
+// Initialize singleton config utils once at module evaluation
+export const config = mergeConfigs<ExtendedGroups>(getDefaultConfig(), {
+  extend: configExtend,
+});
+
+export const configUtils = createConfigUtils(config);

package/src/orders/modifier-order.prettier-plugin-tailwindcss.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import { sortModifierKeys } from './modifier-order.prettier-plugin-tailwindcss';
+
+describe('sortModifierKeys with Tailwind CSS Compiler sorter', () => {
+  it('returns array as is when length <= 1', () => {
+    expect(sortModifierKeys([])).toEqual([]);
+    expect(sortModifierKeys(['hover'])).toEqual(['hover']);
+  });
+
+  it('correctly sorts standard Tailwind CSS modifiers', () => {
+    const input = ['dark:hover', 'hover', 'md', 'dark', 'sm'];
+    const sorted = sortModifierKeys(input);
+
+    expect(sorted).toEqual(['hover', 'sm', 'md', 'dark', 'dark:hover']);
+  });
+
+  it('handles arbitrary variants and bracket syntax without corruption', () => {
+    const input = [
+      'hover',
+      '[@supports(display:grid)]:hover',
+      'dark',
+      '[&_svg]:hover',
+    ];
+    const sorted = sortModifierKeys(input);
+
+    expect(sorted).toEqual([
+      'hover',
+      'dark',
+      '[&_svg]:hover',
+      '[@supports(display:grid)]:hover',
+    ]);
+  });
+});

package/src/orders/modifier-order.prettier-plugin-tailwindcss.ts

@@ -0,0 +1,23 @@
+import { createSorter } from 'prettier-plugin-tailwindcss/sorter';
+
+// Initialize Tailwind Compiler sorter once at module evaluation
+const sorter = await createSorter({});
+const DUMMY_SUFFIX = ':flex';
+
+/**
+ * Sorts modifier keys according to Tailwind CSS Compiler AST order
+ * using dummy classes (e.g. 'hover' -> 'hover:flex').
+ *
+ * @param modifierKeys Array of modifier strings (e.g. ['dark:hover', 'hover', 'md', 'dark', 'sm'])
+ * @returns Sorted array of modifier keys adhering to official Tailwind Compiler order
+ */
+export function sortModifierKeys(modifierKeys: string[]): string[] {
+  if (modifierKeys.length <= 1) {
+    return modifierKeys;
+  }
+
+  const dummyClasses = modifierKeys.map(mod => `${mod}${DUMMY_SUFFIX}`);
+  const [sortedDummyClasses] = sorter.sortClassLists([dummyClasses]);
+
+  return sortedDummyClasses.map(cls => cls.slice(0, -DUMMY_SUFFIX.length));
+}

package/src/prettier.d.ts

@@ -0,0 +1,21 @@
+import type { Options } from 'prettier';
+
+/**
+ * Ambient type augmentation for Prettier Options.
+ *
+ * NOTE: These type definitions correspond directly to the runtime options defined in:
+ * @see {@link ./options.ts}
+ */
+declare module 'prettier' {
+  interface Options {
+    classNameThreshold?: number;
+    modifierThreshold?: number;
+    tailwindFunctions?: string[];
+  }
+}
+
+export interface PluginOptions extends Options {
+  classNameThreshold: number;
+  modifierThreshold: number;
+  tailwindFunctions: string[];
+}

package/src/printers.test.ts

@@ -0,0 +1,58 @@
+import type { Node } from 'estree-jsx';
+import type { ParserOptions } from 'prettier';
+import dedent from 'dedent';
+import { afterEach, beforeEach, describe } from 'vitest';
+import { testFormat } from './__tests__/utils/test-format';
+import { estree } from './ast';
+
+describe('printers preprocess handling: async Promise AST preprocess', () => {
+  let originalPreprocess:
+    | undefined
+    | ((ast: Node, _options: ParserOptions<Node>) => Node | Promise<Node>);
+
+  beforeEach(() => {
+    originalPreprocess = estree.preprocess;
+    estree.preprocess = (ast, _options) => Promise.resolve(ast);
+  });
+
+  afterEach(() => {
+    estree.preprocess = originalPreprocess;
+  });
+
+  testFormat(
+    'correctly handles async Promise returned by estree.preprocess',
+    { 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('printers preprocess handling: fallback when estree.preprocess is undefined (sync path)', () => {
+  let originalPreprocess:
+    | undefined
+    | ((ast: Node, _options: ParserOptions<Node>) => Node | Promise<Node>);
+
+  beforeEach(() => {
+    originalPreprocess = estree.preprocess;
+    estree.preprocess = undefined;
+  });
+
+  afterEach(() => {
+    estree.preprocess = originalPreprocess;
+  });
+
+  testFormat(
+    'uses ast directly if estree.preprocess is undefined',
+    { 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')} />;
+    `,
+  );
+});

package/src/printers.ts

@@ -0,0 +1,29 @@
+import type { Node } from 'estree-jsx';
+import type { Plugin } from 'prettier';
+import estreePlugin from 'prettier/plugins/estree.js';
+import { estree } from './ast';
+import { resolveOptions } from './options';
+import { walkAst } from './printers.walk-ast';
+
+export const printers: Plugin<Node>['printers'] = {
+  estree: {
+    ...estreePlugin.printers.estree,
+    preprocess(ast, options) {
+      const pluginOptions = resolveOptions(options);
+
+      const processedAST = estree.preprocess
+        ? estree.preprocess(ast, options)
+        : ast;
+
+      if (processedAST instanceof Promise) {
+        return processedAST.then(resolvedAst => {
+          walkAst(resolvedAst, pluginOptions);
+          return resolvedAst;
+        });
+      }
+
+      walkAst(processedAST, pluginOptions);
+      return processedAST;
+    },
+  },
+};

package/src/printers.walk-ast.test.ts

@@ -0,0 +1,58 @@
+import type { Node } from 'estree-jsx';
+import { describe, expect, it, vi } from 'vitest';
+import { estree } from './ast';
+import { resolveOptions } from './options';
+import { walkAst } from './printers.walk-ast';
+
+describe('walkAst unit tests', () => {
+  const options = resolveOptions({});
+
+  it('returns early when input is not a valid AST Node', () => {
+    expect(() => walkAst(null as unknown as Node, options)).not.toThrow();
+    expect(() => walkAst(undefined as unknown as Node, options)).not.toThrow();
+    expect(() => walkAst(123 as unknown as Node, options)).not.toThrow();
+    expect(() =>
+      walkAst('not-a-node' as unknown as Node, options),
+    ).not.toThrow();
+    expect(() => walkAst({} as unknown as Node, options)).not.toThrow();
+  });
+
+  it('handles array child properties containing non-node items', () => {
+    const mockNode: any = {
+      type: 'Program',
+      body: [null, undefined, 123, 'string-item', { type: 'EmptyStatement' }],
+    };
+
+    expect(() => walkAst(mockNode, options)).not.toThrow();
+  });
+
+  it('handles non-array child properties that are nodes', () => {
+    const mockNode: any = {
+      type: 'ExpressionStatement',
+      expression: {
+        type: 'Identifier',
+        name: 'foo',
+      },
+    };
+
+    expect(() => walkAst(mockNode, options)).not.toThrow();
+  });
+
+  it('handles truthy non-array child properties that are not nodes', () => {
+    const originalGetVisitorKeys = estree.getVisitorKeys;
+    vi.spyOn(estree, 'getVisitorKeys').mockReturnValue(['someProp'] as any);
+
+    try {
+      const mockNode: any = {
+        type: 'CustomNode',
+        someProp: 'truthy-non-node-primitive',
+      };
+
+      expect(() => walkAst(mockNode, options)).not.toThrow();
+    } finally {
+      if (originalGetVisitorKeys) {
+        estree.getVisitorKeys = originalGetVisitorKeys;
+      }
+    }
+  });
+});

package/src/printers.walk-ast.ts

@@ -0,0 +1,41 @@
+import type { Node } from 'estree-jsx';
+import type { PluginOptions } from './prettier';
+import { estree, isNode } from './ast';
+import {
+  handleTargetCVA,
+  handleTargetJSX,
+  handleTargetObjectProperty,
+} from './handle-targets';
+
+const NON_TRAVERSABLE_KEYS = new Set<string>(['parent', 'comments']);
+
+const TARGET_HANDLERS = [
+  handleTargetJSX,
+  handleTargetCVA,
+  handleTargetObjectProperty,
+] as const;
+
+export function walkAst(node: Node, options: PluginOptions): void {
+  if (!isNode(node)) return;
+
+  for (const handle of TARGET_HANDLERS) {
+    if (handle(node, options)) break;
+  }
+
+  const visitorKeys = estree.getVisitorKeys!(node, NON_TRAVERSABLE_KEYS);
+
+  for (const key of visitorKeys) {
+    const child = node[key as Exclude<keyof typeof node, 'type'>];
+    if (!child) continue;
+
+    if (Array.isArray(child)) {
+      for (const item of child) {
+        if (isNode(item)) {
+          walkAst(item, options);
+        }
+      }
+    } else if (isNode(child)) {
+      walkAst(child, options);
+    }
+  }
+}

package/src/utils/split-classes.ts

@@ -0,0 +1,3 @@
+export function splitClasses(classString: string): string[] {
+  return classString.trim().split(/\s+/).filter(Boolean);
+}