@runtimestudio/tailwind-sort-php 0.2.1 → 0.3.0

package/dist/sorter.d.ts

@@ -11,7 +11,7 @@ import type { SortFn } from './transform.ts';
  */
 export interface SorterOptions {
     /**
-     * Tailwind v4 CSS entry point (`@import "tailwindcss"`, `@theme`, etc.).
+     * Tailwind v4 CSS entry point.
      */
     stylesheet: string;
     /**
@@ -20,8 +20,8 @@ export interface SorterOptions {
     base?: string;
 }
 /**
- * Create a `SortFn` backed by the official `prettier-plugin-tailwindcss` sorting engine, configured with
- * the project's Tailwind v4 stylesheet so custom `@theme` tokens and `@utility` classes sort correctly.
+ * Create a `SortFn` backed by the official `prettier-plugin-tailwindcss` sorting engine,
+ * configured with the project's Tailwind v4 stylesheet so custom tokens and classes sort correctly.
  *
  * Requires `prettier-plugin-tailwindcss` >= 0.8 (the `/sorter` entrypoint).
  *

package/dist/sorter.js

@@ -6,8 +6,8 @@
  * @see transform.ts - consumes the `SortFn` produced here.
  */
 /**
- * Create a `SortFn` backed by the official `prettier-plugin-tailwindcss` sorting engine, configured with
- * the project's Tailwind v4 stylesheet so custom `@theme` tokens and `@utility` classes sort correctly.
+ * Create a `SortFn` backed by the official `prettier-plugin-tailwindcss` sorting engine,
+ * configured with the project's Tailwind v4 stylesheet so custom tokens and classes sort correctly.
  *
  * Requires `prettier-plugin-tailwindcss` >= 0.8 (the `/sorter` entrypoint).
  *
@@ -15,8 +15,7 @@
  * @returns A synchronous `SortFn` for use with `transform()`.
  */
 export async function createTailwindSortFn(opts) {
-    // Dynamic import so the core package works without the dependency
-    // installed (e.g., when only running tests with a mock sorter).
+    // Dynamic import so the core package works without the dependency installed.
     const { createSorter } = await import('prettier-plugin-tailwindcss/sorter');
     const sorter = await createSorter({
         base: opts.base ?? process.cwd(),

package/dist/transform.d.ts

@@ -24,9 +24,13 @@ import { type HtmlScanOptions } from './html.ts';
  */
 export type SortFn = (classes: string[]) => string[];
 /**
- * Combined options for both lexer passes.
+ * Combined options for all lexer passes.
  */
 export interface TransformOptions extends IslandOptions, HtmlScanOptions {
+    /**
+     * Sort classes in PHP string-literal values too. Off by default; see `php-strings.ts` for eligibility.
+     */
+    sortPhpStrings?: boolean;
 }
 /**
  * Rewrite all class attribute values in the template source with sorted classes.

package/dist/transform.js

@@ -18,6 +18,7 @@
  */
 import { findIslands } from "./islands.js";
 import { maskIslands, findClassAttributes } from "./html.js";
+import { findSortablePhpStrings } from "./php-strings.js";
 /**
  * Rewrite all class attribute values in the template source with sorted classes.
  * Everything outside class attribute values is byte-identical in the result; the function is idempotent.
@@ -35,17 +36,32 @@ export function transform(src, sortFn, opts = {}) {
     const islands = findIslands(src, opts);
     const masked = maskIslands(src, islands);
     const attrs = findClassAttributes(masked, opts);
-    // Apply replacements back-to-front so offsets stay valid.
-    let out = src;
-    for (let a = attrs.length - 1; a >= 0; a--) {
-        const { valueStart, valueEnd } = attrs[a];
+    // Collect every edit as a {start, end, text} range, then apply them back-to-front so offsets stay valid.
+    // HTML class-attribute values live outside islands; PHP string values live inside them, so the two sets of
+    // ranges never overlap.
+    const edits = [];
+    for (const { valueStart, valueEnd } of attrs) {
         const original = src.slice(valueStart, valueEnd);
         const inner = islands.filter((isl) => isl.start >= valueStart && isl.end <= valueEnd);
         const rewritten = rewriteValue(original, valueStart, inner, sortFn);
-        if (rewritten !== original) {
-            out = out.slice(0, valueStart) + rewritten + out.slice(valueEnd);
+        if (rewritten !== original)
+            edits.push({ start: valueStart, end: valueEnd, text: rewritten });
+    }
+    if (opts.sortPhpStrings) {
+        for (const { start, end } of findSortablePhpStrings(src, islands)) {
+            const original = src.slice(start, end);
+            const tokens = original.split(/\s+/).filter(Boolean);
+            if (tokens.length < 2)
+                continue; // nothing to reorder; leave byte-identical
+            const rewritten = sortFn(tokens).join(' ');
+            if (rewritten !== original)
+                edits.push({ start, end, text: rewritten });
         }
     }
+    edits.sort((a, b) => b.start - a.start);
+    let out = src;
+    for (const e of edits)
+        out = out.slice(0, e.start) + e.text + out.slice(e.end);
     return out;
 }
 function rewriteValue(value, base, islands, sortFn) {

package/package.json

@@ -1,57 +1,57 @@
 {
-  "name": "@runtimestudio/tailwind-sort-php",
-  "version": "0.2.1",
-  "description": "Tailwind CSS Class Sorter for PHP",
-  "keywords": [
-    "class-sorting",
-    "formatter",
-    "php",
-    "prettier",
-    "tailwindcss",
-    "wordpress"
-  ],
-  "homepage": "https://github.com/runtime-studio-au/tailwind-sort-php#readme",
-  "bugs": "https://github.com/runtime-studio-au/tailwind-sort-php/issues",
-  "license": "MIT",
-  "author": "Greg Sevastos <greg@runtimestudio.com.au> (https://runtimestudio.com.au)",
-  "files": [
-    "dist",
-    "src"
-  ],
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "type": "module",
-  "bin": {
-    "tailwind-sort-php": "dist/cli.js"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/runtime-studio-au/tailwind-sort-php.git"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "prepublishOnly": "npm test && npm run build",
-    "sort": "bun run src/cli.ts",
-    "sort:check": "bun run src/cli.ts --check",
-    "test": "node --test \"test/*.test.ts\""
-  },
-  "devDependencies": {
-    "@types/bun": "latest",
-    "prettier": "^3.8",
-    "prettier-plugin-tailwindcss": "^0.8",
-    "tailwindcss": "^4",
-    "typescript": ">=5.7"
-  },
-  "peerDependencies": {
-    "prettier": ">=3",
-    "prettier-plugin-tailwindcss": ">=0.8"
-  },
-  "engines": {
-    "node": ">=22.18"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
+    "name": "@runtimestudio/tailwind-sort-php",
+    "version": "0.3.0",
+    "description": "Tailwind CSS Class Sorter for PHP",
+    "keywords": [
+        "class-sorting",
+        "formatter",
+        "php",
+        "prettier",
+        "tailwindcss",
+        "wordpress"
+    ],
+    "homepage": "https://github.com/runtime-studio-au/tailwind-sort-php#readme",
+    "bugs": "https://github.com/runtime-studio-au/tailwind-sort-php/issues",
+    "license": "MIT",
+    "author": "Greg Sevastos <greg@runtimestudio.com.au> (https://runtimestudio.com.au)",
+    "files": [
+        "dist",
+        "src"
+    ],
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "type": "module",
+    "bin": {
+        "tailwind-sort-php": "dist/cli.js"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/runtime-studio-au/tailwind-sort-php.git"
+    },
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json",
+        "format": "prettier --write .",
+        "format:check": "prettier --check .",
+        "prepublishOnly": "npm test && npm run build",
+        "sort": "bun run src/cli.ts",
+        "sort:check": "bun run src/cli.ts --check",
+        "test": "node --test \"test/*.test.ts\""
+    },
+    "devDependencies": {
+        "@types/bun": "latest",
+        "prettier": "^3.8",
+        "prettier-plugin-tailwindcss": "^0.8",
+        "tailwindcss": "^4",
+        "typescript": ">=5.7"
+    },
+    "peerDependencies": {
+        "prettier": ">=3",
+        "prettier-plugin-tailwindcss": ">=0.8"
+    },
+    "engines": {
+        "node": ">=22.18"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
 }

package/src/cli.ts

@@ -9,6 +9,7 @@
  * Options:
  *   --stylesheet <path> Tailwind v4 CSS entry
  *   --attr <name> Extra attribute to sort (repeatable)
+ *   --php-source <glob> Also sort class strings in PHP declarations in matching files (repeatable)
  *   --check Don't write; exit 1 if any file needs sorting
  *   --no-short-tags Don't treat bare `<?` as a PHP open tag
  *
@@ -24,11 +25,12 @@ import { runInit } from './init.ts';
 const IGNORE = ['node_modules', 'vendor', 'dist', '.git'];
 
 interface Cli {
-  globs: string[];
-  stylesheet?: string;
-  attrs: string[];
-  check: boolean;
-  shortTags: boolean;
+    globs: string[];
+    stylesheet?: string;
+    attrs: string[];
+    phpSources: string[];
+    check: boolean;
+    shortTags: boolean;
 }
 
 /**
@@ -38,25 +40,27 @@ interface Cli {
  * @returns Parsed CLI options with defaults applied.
  */
 function parseArgs(argv: string[]): Cli {
-  const cli: Cli = {
-    globs: [],
-    attrs: ['class', 'className'],
-    check: false,
-    shortTags: true,
-  };
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === '--check') cli.check = true;
-    else if (a === '--no-short-tags') cli.shortTags = false;
-    else if (a === '--stylesheet') cli.stylesheet = argv[++i];
-    else if (a === '--attr') cli.attrs.push(argv[++i]);
-    else if (a.startsWith('--')) {
-      console.error(`Unknown option: ${a}`);
-      process.exit(2);
-    } else cli.globs.push(a);
-  }
-  if (cli.globs.length === 0) cli.globs.push('**/*.php');
-  return cli;
+    const cli: Cli = {
+        globs: [],
+        attrs: ['class', 'className'],
+        phpSources: [],
+        check: false,
+        shortTags: true,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--check') cli.check = true;
+        else if (a === '--no-short-tags') cli.shortTags = false;
+        else if (a === '--stylesheet') cli.stylesheet = argv[++i];
+        else if (a === '--attr') cli.attrs.push(argv[++i]);
+        else if (a === '--php-source') cli.phpSources.push(argv[++i]);
+        else if (a.startsWith('--')) {
+            console.error(`Unknown option: ${a}`);
+            process.exit(2);
+        } else cli.globs.push(a);
+    }
+    if (cli.globs.length === 0) cli.globs.push('**/*.php');
+    return cli;
 }
 
 /**
@@ -65,17 +69,17 @@ function parseArgs(argv: string[]): Cli {
  * @param globs Glob patterns relative to `cwd`.
  */
 async function* scanFiles(globs: string[]): AsyncGenerator<string> {
-  if (typeof (globalThis as any).Bun !== 'undefined') {
-    const { Glob } = await import('bun');
-    for (const pattern of globs) {
-      for await (const f of new Glob(pattern).scan('.')) yield f;
-    }
-  } else {
-    const { glob } = await import('node:fs/promises');
-    for (const pattern of globs) {
-      for await (const f of glob(pattern)) yield f as string;
+    if (typeof (globalThis as any).Bun !== 'undefined') {
+        const { Glob } = await import('bun');
+        for (const pattern of globs) {
+            for await (const f of new Glob(pattern).scan('.')) yield f;
+        }
+    } else {
+        const { glob } = await import('node:fs/promises');
+        for (const pattern of globs) {
+            for await (const f of glob(pattern)) yield f as string;
+        }
     }
-  }
 }
 
 /**
@@ -87,89 +91,102 @@ async function* scanFiles(globs: string[]): AsyncGenerator<string> {
 const ignored = (file: string) => IGNORE.some((d) => file.includes(`${d}/`) || file.startsWith(d));
 
 /**
- * Best-effort read of the project's resolved Prettier config, so this tool shares one source of truth with
- * `prettier-plugin-tailwindcss`. Picks up `tailwindStylesheet` (resolved relative to the config file) and
- * `tailwindAttributes` (merged into the attribute list).
+ * Best-effort read of the resolved Prettier config — the shared source of truth with `prettier-plugin-tailwindcss`.
+ * Picks up `tailwindStylesheet`, `tailwindAttributes`, and `tailwindPhpSources`.
  *
- * @returns The resolved stylesheet path and attributes, or an empty object if none are available.
+ * @returns The found settings, or an empty object if none are available.
  */
 async function fromPrettierConfig(): Promise<{
-  stylesheet?: string;
-  attributes?: string[];
+    stylesheet?: string;
+    attributes?: string[];
+    phpSources?: string[];
 }> {
-  try {
-    const prettier = await import('prettier');
-    const { dirname, resolve } = await import('node:path');
-    const configFile = await prettier.resolveConfigFile();
-    if (!configFile) return {};
-    const cfg = (await prettier.resolveConfig(configFile)) as Record<string, unknown> | null;
-    if (!cfg) return {};
-    const out: { stylesheet?: string; attributes?: string[] } = {};
-    if (typeof cfg.tailwindStylesheet === 'string') {
-      out.stylesheet = resolve(dirname(configFile), cfg.tailwindStylesheet);
-    }
-    if (Array.isArray(cfg.tailwindAttributes)) {
-      out.attributes = cfg.tailwindAttributes.filter((a): a is string => typeof a === 'string' && !a.startsWith('/'));
+    try {
+        const prettier = await import('prettier');
+        const { dirname, resolve } = await import('node:path');
+        const configFile = await prettier.resolveConfigFile();
+        if (!configFile) return {};
+        const cfg = (await prettier.resolveConfig(configFile)) as Record<string, unknown> | null;
+        if (!cfg) return {};
+        const out: { stylesheet?: string; attributes?: string[]; phpSources?: string[] } = {};
+        if (typeof cfg.tailwindStylesheet === 'string') {
+            out.stylesheet = resolve(dirname(configFile), cfg.tailwindStylesheet);
+        }
+        if (Array.isArray(cfg.tailwindAttributes)) {
+            out.attributes = cfg.tailwindAttributes.filter(
+                (a): a is string => typeof a === 'string' && !a.startsWith('/'),
+            );
+        }
+        if (Array.isArray(cfg.tailwindPhpSources)) {
+            out.phpSources = cfg.tailwindPhpSources.filter((p): p is string => typeof p === 'string');
+        }
+        return out;
+    } catch {
+        return {}; // prettier not installed or config unreadable — flags only
     }
-    return out;
-  } catch {
-    return {}; // prettier not installed or config unreadable — flags only
-  }
 }
 
 async function main() {
-  const argv = process.argv.slice(2);
-  if (argv[0] === 'init') return runInit(argv.slice(1));
-
-  const cli = parseArgs(argv);
-
-  const pc = await fromPrettierConfig();
-  const stylesheet = cli.stylesheet ?? pc.stylesheet;
-  if (!stylesheet) {
-    console.error(
-      'No Tailwind stylesheet found. Pass --stylesheet <path> or set ' +
-        '`tailwindStylesheet` in your Prettier config.',
-    );
-    process.exit(2);
-  }
-  if (pc.attributes) {
-    for (const a of pc.attributes) {
-      if (!cli.attrs.includes(a)) cli.attrs.push(a);
+    const argv = process.argv.slice(2);
+    if (argv[0] === 'init') return runInit(argv.slice(1));
+
+    const cli = parseArgs(argv);
+
+    const pc = await fromPrettierConfig();
+    const stylesheet = cli.stylesheet ?? pc.stylesheet;
+    if (!stylesheet) {
+        console.error(
+            'No Tailwind stylesheet found. Pass --stylesheet <path> or set ' +
+                '`tailwindStylesheet` in your Prettier config.',
+        );
+        process.exit(2);
+    }
+    if (pc.attributes) {
+        for (const a of pc.attributes) {
+            if (!cli.attrs.includes(a)) cli.attrs.push(a);
+        }
+    }
+
+    const sortFn = await createTailwindSortFn({ stylesheet });
+    const opts: TransformOptions = {
+        attributes: cli.attrs,
+        shortOpenTags: cli.shortTags,
+    };
+
+    // Pre-scan the opt-in `tailwindPhpSources` globs; a file gets `sortPhpStrings` only if it matches one.
+    const phpSources = [...cli.phpSources, ...(pc.phpSources ?? [])];
+    const phpSourceFiles = new Set<string>();
+    for await (const file of scanFiles(phpSources)) {
+        if (!ignored(file)) phpSourceFiles.add(file);
     }
-  }
-
-  const sortFn = await createTailwindSortFn({ stylesheet });
-  const opts: TransformOptions = {
-    attributes: cli.attrs,
-    shortOpenTags: cli.shortTags,
-  };
-
-  let scanned = 0;
-  let changed = 0;
-
-  for (const pattern of cli.globs) {
-    for await (const file of scanFiles([pattern])) {
-      if (ignored(file)) continue;
-      scanned++;
-      const src = await readFile(file, 'utf8');
-      const out = transform(src, sortFn, opts);
-      if (out !== src) {
-        changed++;
-        if (cli.check) {
-          console.log(`needs sorting: ${file}`);
-        } else {
-          await writeFile(file, out);
-          console.log(`sorted: ${file}`);
+
+    let scanned = 0;
+    let changed = 0;
+    const seen = new Set<string>();
+
+    // Include php-source files so a designated holder is sorted even outside the main globs; `seen` dedupes.
+    for await (const file of scanFiles([...cli.globs, ...phpSources])) {
+        if (ignored(file) || seen.has(file)) continue;
+        seen.add(file);
+        scanned++;
+        const src = await readFile(file, 'utf8');
+        const out = transform(src, sortFn, { ...opts, sortPhpStrings: phpSourceFiles.has(file) });
+        if (out !== src) {
+            changed++;
+            if (cli.check) {
+                console.log(`needs sorting: ${file}`);
+            } else {
+                await writeFile(file, out);
+                console.log(`sorted: ${file}`);
+            }
         }
-      }
     }
-  }
 
-  console.log(`${scanned} file(s) scanned, ${changed} ${cli.check ? 'need(s) sorting' : 'updated'}`);
-  if (cli.check && changed > 0) process.exit(1);
+    console.log(`${scanned} file(s) scanned, ${changed} ${cli.check ? 'need(s) sorting' : 'updated'}`);
+    if (cli.check && changed > 0) process.exit(1);
 }
 
 main().catch((err) => {
-  console.error(err);
-  process.exit(1);
+    console.error(err);
+    process.exit(1);
 });