@runtimestudio/tailwind-sort-php 0.2.0 → 0.3.0

package/dist/php-strings.js

@@ -0,0 +1,230 @@
+/**
+ * PHP string-literal harvester — the optional third pass.
+ *
+ * Given the source and the PHP islands already found by `findIslands()`, this locates the byte ranges of every
+ * string literal *value* inside PHP code that is eligible for class sorting, applying these structural rules:
+ *
+ *   - Only the *value* of a `key => value` pair is eligible; array keys are never sorted.
+ *   - Bare list-style elements (`['a', 'b']`) and scalar assignments (`const X = '...'`) are values.
+ *   - Strings that are part of a concatenation expression (`'btn-' . $v`) are skipped — a literal joined to dynamic
+ *     code may be a partial class fragment, and reordering it would corrupt the rendered string.
+ *   - Double-quoted strings containing interpolation (`"p-4 {$x}"`) are skipped, mirroring the HTML side's
+ *     conservatism around dynamic content.
+ *   - Strings whose body contains a backslash escape are skipped, so escape sequences can never be mangled.
+ *   - Heredoc/nowdoc and backtick (shell-exec) strings are never harvested.
+ *
+ * This pass is opt-in per file (the caller decides which files are class-string holders); it does NOT judge whether
+ * a given string "looks like" Tailwind classes — within a matched file, every eligible value is sorted.
+ *
+ * @see islands.ts   - first pass; produces the islands consumed here.
+ * @see transform.ts - splices the sorted strings back via the shared byte-replacement path.
+ */
+const isIdentStart = (c) => /[A-Za-z_€-￿]/.test(c);
+const isIdent = (c) => /[A-Za-z0-9_€-￿]/.test(c);
+/**
+ * Find every sortable string-literal value within the given PHP islands.
+ *
+ * @param src     Original template source.
+ * @param islands Island ranges from `findIslands()`.
+ * @returns Inner ranges of eligible string values, in document order.
+ *
+ * @example
+ * const islands = findIslands(`<?php $x = 'z a'; ?>`);
+ * findSortablePhpStrings(`<?php $x = 'z a'; ?>`, islands); // [{ start: 11, end: 14 }]
+ */
+export function findSortablePhpStrings(src, islands) {
+    const ranges = [];
+    for (const isl of islands) {
+        const tokens = tokenizeIsland(src, isl.start, isl.end);
+        for (let k = 0; k < tokens.length; k++) {
+            const token = tokens[k];
+            if (token.kind !== 'string' || token.skip)
+                continue;
+            const next = tokens[k + 1];
+            const prev = tokens[k - 1];
+            // Array key (`'left' => ...`) — never sorted.
+            if (next && next.kind === 'arrow')
+                continue;
+            // Part of a concatenation expression (`'btn-' . $v` / `$v . 'suffix'`).
+            if ((next && next.kind === 'dot') || (prev && prev.kind === 'dot'))
+                continue;
+            ranges.push({ start: token.start, end: token.end });
+        }
+    }
+    return ranges;
+}
+/**
+ * Tokenize one PHP island into the minimal token stream needed for value classification: string literals
+ * (with their inner range and a skip flag), the `=>` arrow, the `.` concatenation operator, and a coalesced `other`
+ * marker for everything else. Whitespace and comments are dropped so adjacency is judged across them.
+ */
+function tokenizeIsland(src, start, end) {
+    const tokens = [];
+    const pushOther = () => {
+        if (tokens.length === 0 || tokens[tokens.length - 1].kind !== 'other')
+            tokens.push({ kind: 'other' });
+    };
+    let i = start;
+    while (i < end) {
+        const c = src[i];
+        // Whitespace.
+        if (c === ' ' || c === '\t' || c === '\n' || c === '\r' || c === '\f' || c === '\v') {
+            i++;
+            continue;
+        }
+        // Line comments (`//`, `#`) — but `#[` opens a PHP 8 attribute, which is code.
+        if (c === '/' && src[i + 1] === '/') {
+            i = skipLineComment(src, i + 2, end);
+            continue;
+        }
+        if (c === '#' && src[i + 1] !== '[') {
+            i = skipLineComment(src, i + 1, end);
+            continue;
+        }
+        // Block comment.
+        if (c === '/' && src[i + 1] === '*') {
+            const close = src.indexOf('*/', i + 2);
+            i = close === -1 || close + 2 > end ? end : close + 2;
+            continue;
+        }
+        // Heredoc / nowdoc — never harvested; skip the whole construct.
+        if (c === '<' && src[i + 1] === '<' && src[i + 2] === '<') {
+            const here = skipHeredoc(src, i + 3, end);
+            if (here !== -1) {
+                i = here;
+                pushOther();
+                continue;
+            }
+        }
+        // Quoted strings.
+        if (c === "'") {
+            const close = scanQuoted(src, i + 1, "'", end);
+            const inner = src.slice(i + 1, close);
+            tokens.push({ kind: 'string', start: i + 1, end: close, skip: inner.includes('\\') });
+            i = close + 1;
+            continue;
+        }
+        if (c === '"') {
+            const close = scanQuoted(src, i + 1, '"', end);
+            const inner = src.slice(i + 1, close);
+            // Skip interpolation (any unescaped `$`) and escapes.
+            tokens.push({ kind: 'string', start: i + 1, end: close, skip: hasInterpolationOrEscape(inner) });
+            i = close + 1;
+            continue;
+        }
+        if (c === '`') {
+            // Shell-exec string — never a class list.
+            i = scanQuoted(src, i + 1, '`', end) + 1;
+            pushOther();
+            continue;
+        }
+        // Operators that matter for classification.
+        if (c === '=' && src[i + 1] === '>') {
+            tokens.push({ kind: 'arrow' });
+            i += 2;
+            continue;
+        }
+        if (c === '.') {
+            tokens.push({ kind: 'dot' });
+            i++;
+            continue;
+        }
+        // Everything else (identifiers, punctuation, the `<?php`/`?>` tags themselves).
+        pushOther();
+        if (isIdentStart(c)) {
+            i++;
+            while (i < end && isIdent(src[i]))
+                i++;
+        }
+        else {
+            i++;
+        }
+    }
+    return tokens;
+}
+/**
+ * Scan a quoted string body; `i` is just past the open quote. Returns the offset of the closing quote (or `end`).
+ */
+function scanQuoted(src, i, quote, end) {
+    while (i < end) {
+        const c = src[i];
+        if (c === '\\') {
+            i += 2;
+            continue;
+        }
+        if (c === quote)
+            return i;
+        i++;
+    }
+    return end;
+}
+/**
+ * Skip a `//`/`#` line comment body, ending at a newline or `?>`. Returns the offset to resume scanning from.
+ */
+function skipLineComment(src, i, end) {
+    while (i < end) {
+        if (src[i] === '\n')
+            return i + 1;
+        if (src[i] === '?' && src[i + 1] === '>')
+            return i;
+        i++;
+    }
+    return end;
+}
+/**
+ * True if a double-quoted body contains interpolation (an unescaped `$`) or any escape sequence.
+ */
+function hasInterpolationOrEscape(body) {
+    for (let i = 0; i < body.length; i++) {
+        const c = body[i];
+        if (c === '\\')
+            return true;
+        if (c === '$')
+            return true;
+    }
+    return false;
+}
+/**
+ * Skip a heredoc/nowdoc; `i` is just past `<<<`. Returns the offset past the closing identifier line,
+ * or -1 if `<<<` isn't followed by a valid heredoc identifier. Mirrors the boundary rules of the island lexer.
+ */
+function skipHeredoc(src, i, end) {
+    while (i < end && (src[i] === ' ' || src[i] === '\t'))
+        i++;
+    let quote = '';
+    if (src[i] === "'" || src[i] === '"') {
+        quote = src[i];
+        i++;
+    }
+    if (i >= end || !isIdentStart(src[i]))
+        return -1;
+    const idStart = i;
+    while (i < end && isIdent(src[i]))
+        i++;
+    const id = src.slice(idStart, i);
+    if (quote) {
+        if (src[i] !== quote)
+            return -1;
+        i++;
+    }
+    while (i < end && src[i] === '\r')
+        i++;
+    if (src[i] !== '\n')
+        return -1;
+    i++;
+    while (i < end) {
+        let j = i;
+        while (j < end && (src[j] === ' ' || src[j] === '\t'))
+            j++;
+        if (src.startsWith(id, j)) {
+            const k = j + id.length;
+            if (k >= end || !isIdent(src[k]))
+                return k;
+        }
+        const nl = src.indexOf('\n', i);
+        if (nl === -1 || nl >= end)
+            return end;
+        i = nl + 1;
+    }
+    return end;
+}

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.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"
-  }
+    "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"
+    }
 }