@plaudit/webpack-extensions 2.60.0 → 2.60.1

package/LICENSE.md

@@ -0,0 +1,13 @@
+# License
+
+Unless otherwise stated in a written and signed agreement with Plaudit, the following license terms apply to this software:
+* **Definitions**: ‘Client’ means the legal entity that has engaged Plaudit under a signed Master Services Agreement (MSA) or similar written contract for a project with which this library is provided. ‘Authorized Vendors’ means Client’s employees, contractors, and third‑party service providers who access this library solely on Client’s behalf.
+* **Use**: This library shall remain the exclusive property of Plaudit. Plaudit hereby grants the Client a nonexclusive, nontransferable, worldwide license to use this library only as necessary to use and maintain the final deliverables provided by Plaudit for Client. Authorized Vendors obtain no rights independent of Client, may not sublicense or transfer, and must comply with these restrictions. Client and Authorized Vendors may not directly or indirectly create derivative works or use the library for any other client or project.
+* **Access and Transfer**: Access by Authorized Vendors is permitted only while performing services for Client on the relevant deliverables and must be subject to written obligations no less protective than these terms. Access ends when such services end.
+* **Warranty Disclaimer**: This software is provided **“as is”** without warranty of any kind. Plaudit disclaims all warranties, express or implied, including but not limited to warranties of merchantability, fitness for a particular purpose, and non-infringement.
+* **Limitation of Liability**: In no event shall Plaudit be liable for any damages, liabilities, costs, losses, or expenses arising out of or in connection with the use of this software, including but not limited to incidental, consequential, or punitive damages, even if advised of the possibility of such damages.
+* **Support and Updates**: No support, maintenance, or future updates are provided under this license. The license does not grant rights to future versions of this software.
+
+---
+
+(License revision: 1.0)

package/README.md

@@ -1,5 +1,94 @@
+# Plaudit Webpack Extensions
+A webpack configuration and plugin suite designed specifically for WordPress development workflows. This package extends `@wordpress/scripts` with custom webpack plugins, PostCSS configurations, and build optimizations tailored for Plaudit's WordPress projects. It includes specialized handling for Gutenberg blocks, asset management, internationalization (WPML), and development tooling like BrowserSync integration.
+
+# Requirements
+- All block- and extension-related capabilities require that the `plaudit/plaudit-common` composer library be installed.
+- All assets must be under a unified root directory and must be emitted to a unified output directory
+  - Ex: `src/blocks` and `src/extensions` emitting to `dist/blocks` and `dist/extensions`
+
+# Perks
+## Truly automatic asset loading
+With the `useUnifiedLoader` flag enabled (see the usage example), this package will generate a single file that, when included, automatically registers and enqueues scripts, styles, and assets.
+This includes prefetching assets when the `useWebpackResourceFiltering` flag is enabled.
+
+## Automatic filename mapping in `block.json`
+Instead of requiring developers to plug in the built names of files when developing blocks, this suite will automatically replace the source name with the built name in emitted block.json files *and* will automatically resolve filename conflicts that would otherwise cause the build to fail.
+
+In addition to handling filename conflicts, it also automatically detects the presence of `template.php` and `template.twig` files and ensures that they are properly registered in the emitted block.json files.
+
+## Efficient loading
+This suite generates loader code that uses the most efficient mechanisms available for registering assets, and, in the case of blocks in themes, a loading mechanism that is more efficient than any "available" method.
+
+## Unified Plugin and Theme Structures
+The same file structure (both in the webpack.config.js file and the actual directory tree) can be used in plugins and themes.
+
+# Usage
+## An Example Config
+NOTE: This config assumes that `require_once __DIR__.'/dist/unified-loader.php';` has been added to the theme's functions.php file or the plugin's main PHP file
+
+```javascript
+module.exports = require("@plaudit/webpack-extensions/wordpress-scripts-wrapper")({
+	src: {
+		"blocks": true, // By default, a directory is assumed to contain WordPress blocks, so we don't need to do anything other than tell WebPack to include it
+		"extensions": { // Extensions need to have their directory layout specified, but the loader is automatically generated, so there's no need to specify an output path
+			directoryLayout: 'extensions'
+		},
+		"site/index-header.ts": { // "Plain" entrypoints (i.e. those not associated with a block or extension) can have their usage locations specified, at which point they will also be automatically loaded
+			locations: {
+				clientView: true,
+				registerScriptArgs: false
+			}
+		},
+		"site/index-footer.ts": {
+			withLegacyBlocksIn: "blocks",
+			locations: {
+				clientView: true,
+				registerScriptArgs: {strategy: "defer", in_footer: true}
+			}
+		},
+		"site/wp-admin.ts": {
+			locations: {
+				admin: true
+			}
+		},
+		"site/wp-admin.pcss": {
+			locations: {
+				admin: true
+			}
+		},
+		"site/block-editor.pcss": {
+			locations: {
+				clientEditor: true
+			}
+		},
+		"site/public.pcss": {
+			locations: {
+				clientView: true
+			}
+		}
+	},
+	useWebpackResourceFiltering: true,
+	extensionsVersion: 2,
+	plainEntrypointsVersion: 2,
+	srcDir: "src",
+	outputDir: "dist",
+	useUnifiedLoader: true
+});
+```
+
 # Development
-To test locally, either set up yarn to pull from this folder or (ideally) build and copy the resulting built files into another project for testing purposes.
+
+## Setup
+
+```
+pnpm install
+```
+
+# Build
+
+```
+pnpm build
+```
 
 # To Deploy
 ```

package/build/plugins/BlockJSONManagingPlugin.js

@@ -329,7 +329,7 @@ class BlockJSONManagingPlugin {
                         .use("Plaudit\\Common\\ACF\\BlockManager")
                         .action("init", writer => {
                         writer.call("BlockManager::autoloadSubfolders", [new php_writer_1.Expr(`__DIR__.${php_writer_1.Expr.convertJsonToPHP("/" + this.blocksDest)}`)]);
-                    });
+                    }, { accountForAlreadyDoing: true });
                 }
             });
         });

package/build/plugins/PlainEntrypointsConfigFileGeneratorPlugin.js

@@ -182,7 +182,7 @@ class PlainEntrypointsConfigFileGeneratorPlugin {
                     for (const { handle, type, data } of prioritizedHandleList) {
                         writer.call(`wp_register_${type}`, [handle, new php_writer_1.Expr(`$base_uri.${php_writer_1.Expr.jsonToPHPConverter(node_path_1.default.relative(emitDir, data.src))}`), ...data.rest]);
                     }
-                }, { priority });
+                }, { priority, accountForAlreadyDoing: true });
             }
             const sortedEditorStyleHandles = sortedStyleHandles
                 .filter(([_, { locations: { clientEditor }, isScript }]) => !isScript && (clientEditor || typeof clientEditor === 'number'))
@@ -227,7 +227,7 @@ class PlainEntrypointsConfigFileGeneratorPlugin {
         for (const [action, handleList] of enqueuingHandleActions) {
             if (handleList.length > 0) {
                 for (const [priority, prioritizedHandleList] of PlainEntrypointsConfigFileGeneratorPlugin.separateHandleListByPriority(handleList)) {
-                    writer.action(action, () => {
+                    writer.action(action, writer => {
                         for (const handle of prioritizedHandleList) {
                             writer.call(`wp_enqueue_${handle.type}`, [handle.handle]);
                         }
@@ -253,7 +253,7 @@ class PlainEntrypointsConfigFileGeneratorPlugin {
      * The primary benefit of emitting a function instead of baking its contents into each function that uses it is that it allows us to avoid recomputing the base uri multiple times
      */
     static emitResolveBaseUriFunction(writer) {
-        writer.function("plaudit_webpack_extensions__resolve_base_uri", ["$dir"], () => {
+        writer.function("plaudit_webpack_extensions__resolve_base_uri", ["$dir"], writer => {
             writer
                 .static("$base_uris", { initializer: [] })
                 .if("isset($base_uris[$dir])")

package/build/plugins/SpecialAssetHandlingPlugin.js

@@ -136,7 +136,7 @@ class SpecialAssetHandlingPlugin {
                 writer.append(`<link rel="preload" href="<?= esc_url($base_uri.'${filename}') ?>" ${dynamicAttrs}>`);
             }
             writer.openPHP();
-        });
+        }, { accountForAlreadyDoing: true });
         writer.emitAsset(compilation, outputFile);
     }
 }

package/build/utils/php-writer.d.ts

@@ -11,23 +11,30 @@ export type ActionOrFilterArgs = {
     priority?: number | Expr;
     functionArgParameters?: string[];
     useVars?: string[];
+    accountForAlreadyDoing?: boolean | Parameters<PHPWriter['call']>[1];
 };
 export type FunctionCreationArgs = {
     includeExistenceCheck?: boolean;
     useVars?: string[];
     returnType?: string;
+    assignToName?: boolean;
+    scopeActionDescription?: string;
 };
 export declare class PHPWriter {
     private readonly inlineFirstLine;
+    private readonly scopeStack;
+    private readonly useList;
+    private readonly allocatedGeneratedFunctionNames;
+    private printingInPHP;
     private buffer;
     private indentation;
-    private printingInPHP;
     private fileNamespace;
-    private useList;
-    private scopeStack;
-    constructor(inlineFirstLine?: boolean);
+    private myOpenedScopes;
+    constructor(inlineFirstLine?: boolean, scopeStack?: string[][], useList?: string[], allocatedGeneratedFunctionNames?: Set<string>, printingInPHP?: boolean, initialIndentation?: number);
+    createSubwriter(): PHPWriter;
     indent(): this;
     outdent(): this;
+    setIndentation(level: number): this;
     append(...lines: (string | Expr)[]): this;
     assign(variable: string | string[], expression: unknown | Expr, opts?: {
         chain?: boolean;
@@ -44,14 +51,16 @@ export declare class PHPWriter {
         assignTo?: string | string[];
         return?: boolean;
     }): this;
-    action(name: string | Expr, contents: (writer: this) => void, args?: ActionOrFilterArgs): this;
-    filter(name: string | Expr, contents: (writer: this) => void, args?: ActionOrFilterArgs): this;
-    actionOrFilter(type: 'action' | 'filter', name: string | Expr, contents: (writer: this) => void, args: ActionOrFilterArgs): this;
+    action(name: string | Expr, contents: (writer: PHPWriter) => void, args?: ActionOrFilterArgs): this;
+    filter(name: string | Expr, contents: (writer: PHPWriter) => void, args?: ActionOrFilterArgs): this;
+    actionOrFilter(type: 'action' | 'filter', name: string | Expr, contents: (writer: PHPWriter) => void, args: ActionOrFilterArgs): this;
     if(condition: string): this;
     elseIf(condition: string): this;
     else(): this;
     endIf(): this;
-    function(name: string, parameters: string[], body: (writer: this) => void, args?: FunctionCreationArgs): this;
+    function(name: true, parameters: string[], body: (writer: PHPWriter) => void, args?: FunctionCreationArgs): string;
+    function(name: string | false, parameters: string[], body: (writer: PHPWriter) => void, args?: FunctionCreationArgs): this;
+    generateFunctionName(asVariable?: boolean): string;
     closePHP(): this;
     openPHP(): this;
     namespace(namespace: string): this;
@@ -70,10 +79,12 @@ export declare class PHPWriter {
      * This is used to allow function bodies to be safely created without disrupting their containing scope.
      */
     popScope(): this;
-    withScope(code: (writer: this) => void, opts?: {
+    withScope(code: (writer: PHPWriter) => void, opts?: {
         actionDescription?: string;
         usePopScopeInstead?: boolean;
     }): this;
-    toString(): string;
+    toString(args?: {
+        includeOpenPHP?: boolean;
+    }): string;
     emitAsset(compilation: Compilation, file: string, assetInfo?: AssetInfo): void;
 }

package/build/utils/php-writer.js

@@ -22,14 +22,25 @@ class Expr {
 exports.Expr = Expr;
 class PHPWriter {
     inlineFirstLine;
+    scopeStack;
+    useList;
+    allocatedGeneratedFunctionNames;
+    printingInPHP;
     buffer = [];
-    indentation = "";
-    printingInPHP = true;
+    indentation;
     fileNamespace = "";
-    useList = [];
-    scopeStack = [];
-    constructor(inlineFirstLine = false) {
+    myOpenedScopes = 0;
+    constructor(inlineFirstLine = false, scopeStack = [], useList = [], allocatedGeneratedFunctionNames = new Set(), printingInPHP = true, initialIndentation = 0) {
         this.inlineFirstLine = inlineFirstLine;
+        this.scopeStack = scopeStack;
+        this.useList = useList;
+        this.allocatedGeneratedFunctionNames = allocatedGeneratedFunctionNames;
+        this.printingInPHP = printingInPHP;
+        this.indentation = "\t".repeat(initialIndentation);
+    }
+    createSubwriter() {
+        return new PHPWriter(false, this.scopeStack, this.useList, this.allocatedGeneratedFunctionNames, this.printingInPHP, this.indentation.length)
+            .setIndentation(this.indentation.length);
     }
     indent() {
         this.indentation += "\t";
@@ -39,6 +50,10 @@ class PHPWriter {
         this.indentation = this.indentation.slice(0, -1);
         return this;
     }
+    setIndentation(level) {
+        this.indentation = "\t".repeat(level);
+        return this;
+    }
     append(...lines) {
         for (const line of lines) {
             this.buffer.push(`${this.indentation}${line}`);
@@ -103,31 +118,44 @@ class PHPWriter {
         return this.actionOrFilter('filter', name, contents, args);
     }
     actionOrFilter(type, name, contents, args) {
-        const { priority = 10, functionArgParameters = [], useVars = [] } = args;
-        // The trailing comma inside the first item is necessary
-        const declarationComponents = [`${Expr.convertJsonToPHP(name)},`, `function(${functionArgParameters.join(", ")})`];
-        if (useVars.length > 0) {
-            declarationComponents.push(`use (${useVars.join(", ")})`);
+        const { priority = 10, functionArgParameters = [], useVars = [], accountForAlreadyDoing } = args;
+        const functionWriter = this.createSubwriter();
+        let declarationFunctionText;
+        if (accountForAlreadyDoing) {
+            if (functionArgParameters.length > 0 && accountForAlreadyDoing === true) {
+                console.trace(`The accountForAlreadyDoing flag must be set to a list of default parameters when applied to ${type}s that take arguments`);
+            }
+            this.openPHP().openScope();
+            const functionName = functionWriter.function(true, functionArgParameters, contents, { useVars, scopeActionDescription: `closing the function call for the ${name} ${type}.`, assignToName: true });
+            this.append(functionWriter.toString({ includeOpenPHP: false }).trim());
+            declarationFunctionText = functionName + "(...)";
+            this.if(`doing_${type}(${Expr.convertJsonToPHP(name)})`).call(functionName, accountForAlreadyDoing === true ? [] : accountForAlreadyDoing);
         }
-        declarationComponents.push("{");
-        this.openPHP().append(`add_${type}(${declarationComponents.join(" ")}`);
-        this.indent();
-        // We start a new scope here just in case this was called within an existing scope
-        // We pop the scope instead of closing it because we don't actually want to unset any variables that were created within the function
-        this.withScope(contents, { actionDescription: `closing the function call for the ${name} ${type}.`, usePopScopeInstead: true });
-        this.openPHP().outdent();
-        const actionOrFilterArgs = ["}"];
+        else {
+            functionWriter.function(false, functionArgParameters, contents, { useVars, scopeActionDescription: `closing the function call for the ${name} ${type}.` });
+            declarationFunctionText = functionWriter.toString({ includeOpenPHP: false }).trim();
+        }
+        // The trailing comma inside the first item is necessary
+        const declarationComponents = [`${Expr.convertJsonToPHP(name)}`, declarationFunctionText];
         const accepted_args = Math.max(functionArgParameters.length, 1); // This avoids us unnecessarily setting the accepted_args value to 0 for actions
         if (priority !== 10) {
-            actionOrFilterArgs.push(priority.toString());
+            declarationComponents.push(priority.toString());
             if (accepted_args !== 1) {
-                actionOrFilterArgs.push(accepted_args.toString());
+                declarationComponents.push(accepted_args.toString());
             }
         }
         else if (accepted_args !== 1) {
-            actionOrFilterArgs.push(`accepted_args: ${accepted_args}`);
+            declarationComponents.push(`accepted_args: ${accepted_args}`);
         }
-        return this.append(actionOrFilterArgs.join(", ") + ");");
+        const line = `add_${type}(${declarationComponents.join(", ")});`;
+        if (accountForAlreadyDoing) {
+            return this
+                .else()
+                .append(line)
+                .endIf()
+                .closeScope();
+        }
+        return this.openPHP().append(line);
     }
     if(condition) {
         return this.openPHP().append(`if (${condition}) {`).indent();
@@ -142,14 +170,31 @@ class PHPWriter {
         return this.openPHP().outdent().append("}");
     }
     function(name, parameters, body, args = {}) {
+        if (name === false) {
+            if (args.includeExistenceCheck) {
+                console.trace('Anonymous functions cannot have their existence checked for');
+            }
+            if (args.assignToName) {
+                console.trace('Anonymous functions cannot be assigned to a name');
+            }
+        }
+        const returningString = name === true;
+        if (name === true) {
+            name = this.generateFunctionName(args.assignToName);
+        }
         if (args.includeExistenceCheck) {
             this.if(`!function_exists(${Expr.convertJsonToPHP(name)})`);
         }
         else {
             this.openPHP();
         }
-        let nameAndParameters = `${name}(${parameters.join(", ")})`;
-        const declarationComponents = ["function",];
+        if (name !== false && args.assignToName) {
+            if (this.scopeStack.length > 0) {
+                this.scopeStack[this.scopeStack.length - 1].push(name);
+            }
+        }
+        const declarationComponents = name === false ? [] : (args.assignToName ? [name, '='] : ["function"]);
+        let nameAndParameters = `${!name || args.assignToName ? 'function' : name}(${parameters.join(", ")})`;
         if (args.useVars?.length) {
             let useVars = `use (${args.useVars.join(", ")})`;
             if (args.returnType) {
@@ -168,12 +213,21 @@ class PHPWriter {
         this.indent();
         // We start a new scope here just in case this was called within an existing scope
         // We pop the scope instead of closing it because we don't actually want to unset any variables that were created within the function
-        this.withScope(body, { actionDescription: `closing the "${name}" function`, usePopScopeInstead: true });
-        this.openPHP().outdent().append("}");
+        this.withScope(body, { actionDescription: args.scopeActionDescription ?? `closing the "${name || "anonymous"}" function`, usePopScopeInstead: true });
+        this.openPHP().outdent().append(name !== false && args.assignToName ? "};" : "}");
         if (args.includeExistenceCheck) {
-            return this.endIf();
+            this.endIf();
         }
-        return this;
+        return returningString ? name : this;
+    }
+    generateFunctionName(asVariable = false) {
+        let count = 0;
+        let name;
+        do {
+            name = `${asVariable ? '$' : ''}plaudit_webpack_extensions__generated_function__${count++}`;
+        } while (this.allocatedGeneratedFunctionNames.has(name));
+        this.allocatedGeneratedFunctionNames.add(name);
+        return name;
     }
     closePHP() {
         if (!this.printingInPHP) {
@@ -207,21 +261,35 @@ class PHPWriter {
      */
     openScope() {
         this.scopeStack.push([]);
+        this.myOpenedScopes++;
         return this;
     }
     /**
      * Pops the top scope from the stack AND unsets all variables that were assigned within it
      */
     closeScope() {
+        if (!this.myOpenedScopes) {
+            return this;
+        }
+        this.myOpenedScopes--;
         const scope = this.scopeStack.pop();
-        return scope?.length ? this.call("unset", scope.map(v => new Expr(v))) : this;
+        if (!scope?.length) {
+            return this;
+        }
+        for (const scopeItem of scope) {
+            this.allocatedGeneratedFunctionNames.delete(scopeItem);
+        }
+        return this.call("unset", scope.map(v => new Expr(v)));
     }
     /**
      * Pops the top scope from the stack WITHOUT calling unset for the variables that were assigned within it.
      * This is used to allow function bodies to be safely created without disrupting their containing scope.
      */
     popScope() {
-        this.scopeStack.pop();
+        if (this.myOpenedScopes) {
+            this.scopeStack.pop();
+            this.myOpenedScopes--;
+        }
         return this;
     }
     withScope(code, opts = {}) {
@@ -239,8 +307,8 @@ class PHPWriter {
         }
         return this;
     }
-    toString() {
-        if (this.scopeStack.length) {
+    toString(args = {}) {
+        if (this.myOpenedScopes) {
             console.trace("toString() was called on a PHPWriter that has a dangling scope");
         }
         const fileContents = [];
@@ -254,6 +322,9 @@ class PHPWriter {
             fileContents.push(...this.useList.map(use => `use ${use};`));
         }
         fileContents.push(...this.buffer);
+        if (args.includeOpenPHP === false) {
+            return fileContents.join("\n");
+        }
         if (this.inlineFirstLine && canInline) {
             return `<?php ${fileContents.join("\n")}`;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plaudit/webpack-extensions",
-  "version": "2.60.0",
+  "version": "2.60.1",
   "license": "UNLICENSED",
   "files": [
     "/build"