@wp-playground/blueprints 0.1.45 → 0.1.49

package/lib/steps/activate-plugin.d.ts

@@ -1,7 +1,7 @@
 import { StepHandler } from '.';
 export interface ActivatePluginStep {
     step: 'activatePlugin';
-    plugin: string;
+    pluginPath: string;
 }
 /**
  * Activates a WordPress plugin in the Playground.

package/lib/steps/activate-theme.d.ts

@@ -0,0 +1,12 @@
+import { StepHandler } from '.';
+export interface ActivateThemeStep {
+    step: 'activateTheme';
+    themeFolderName: string;
+}
+/**
+ * Activates a WordPress theme in the Playground.
+ *
+ * @param playground The playground client.
+ * @param themeFolderName The theme folder name.
+ */
+export declare const activateTheme: StepHandler<ActivateThemeStep>;

package/lib/steps/client-methods.d.ts

@@ -1,56 +1,230 @@
 import { PHPRunOptions, PHPRequest } from '@php-wasm/universal';
 import { StepHandler } from '.';
+/**
+ * @inheritDoc runPHP
+ * @hasRunnableExample
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "runPHP",
+ * 		"code": "<?php echo 'Hello World'; ?>"
+ * }
+ * </code>
+ */
 export interface RunPHPStep {
+    /** The step identifier. */
     step: 'runPHP';
+    /** The PHP code to run. */
     code: string;
 }
+/**
+ * Runs PHP code.
+ */
 export declare const runPHP: StepHandler<RunPHPStep>;
+/**
+ * @inheritDoc runPHP
+ * @hasRunnableExample
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "runPHP",
+ * 		"options": {
+ * 			"code": "<?php echo $_SERVER['HTTP_CONTENT_TYPE']; ?>",
+ * 			"headers": {
+ * 				"Content-type": "text/plain"
+ * 			}
+ * 		}
+ * }
+ * </code>
+ */
 export interface RunPHPWithOptionsStep {
     step: 'runPHPWithOptions';
     options: PHPRunOptions;
 }
+/**
+ * Runs PHP code with the given options.
+ */
 export declare const runPHPWithOptions: StepHandler<RunPHPWithOptionsStep>;
+/**
+ * @inheritDoc setPhpIniEntry
+ * @hasRunnableExample
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "setPhpIniEntry",
+ * 		"key": "display_errors",
+ * 		"value": "1"
+ * }
+ * </code>
+ */
 export interface SetPhpIniEntryStep {
     step: 'setPhpIniEntry';
     key: string;
     value: string;
 }
+/**
+ * Sets a PHP ini entry.
+ */
 export declare const setPhpIniEntry: StepHandler<SetPhpIniEntryStep>;
+/**
+ * @inheritDoc request
+ * @needsLogin
+ * @hasRunnableExample
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "request",
+ * 		"request": {
+ * 			"method": "POST",
+ * 			"url": "/wp-admin/admin-ajax.php",
+ * 			"formData": {
+ * 				"action": "my_action",
+ * 				"foo": "bar"
+ * 			}
+ * 		}
+ * }
+ * </code>
+ */
 export interface RequestStep {
     step: 'request';
     request: PHPRequest;
 }
+/**
+ * Sends a HTTP request to the Playground.
+ */
 export declare const request: StepHandler<RequestStep>;
+/**
+ * @inheritDoc cp
+ * @hasRunnableExample
+ * @landingPage /index2.php
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "cp",
+ * 		"fromPath": "/wordpress/index.php",
+ * 		"toPath": "/wordpress/index2.php"
+ * }
+ * </code>
+ */
 export interface CpStep {
     step: 'cp';
     fromPath: string;
     toPath: string;
 }
+/**
+ * Copies a file from one path to another.
+ */
 export declare const cp: StepHandler<CpStep>;
+/**
+ * @inheritDoc mv
+ * @hasRunnableExample
+ * @landingPage /index2.php
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "mv",
+ * 		"fromPath": "/wordpress/index.php",
+ * 		"toPath": "/wordpress/index2.php"
+ * }
+ * </code>
+ */
 export interface MvStep {
     step: 'mv';
     fromPath: string;
     toPath: string;
 }
+/**
+ * Moves a file or directory from one path to another.
+ */
 export declare const mv: StepHandler<MvStep>;
+/**
+ * @inheritDoc mkdir
+ * @hasRunnableExample
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "mkdir",
+ * 		"path": "/wordpress/my-new-folder"
+ * }
+ * </code>
+ */
 export interface MkdirStep {
     step: 'mkdir';
     path: string;
 }
+/**
+ * Creates a directory at the specified path.
+ */
 export declare const mkdir: StepHandler<MkdirStep>;
+/**
+ * @inheritDoc rm
+ * @hasRunnableExample
+ * @landingPage /index.php
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "rm",
+ * 		"path": "/wordpress/index.php"
+ * }
+ * </code>
+ */
 export interface RmStep {
     step: 'rm';
     path: string;
 }
+/**
+ * Removes a file at the specified path.
+ */
 export declare const rm: StepHandler<RmStep>;
+/**
+ * @inheritDoc rmdir
+ * @hasRunnableExample
+ * @landingPage /wp-admin/
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "rm",
+ * 		"path": "/wordpress/wp-admin"
+ * }
+ * </code>
+ */
 export interface RmdirStep {
     step: 'rmdir';
     path: string;
 }
+/**
+ * Removes a directory at the specified path.
+ */
 export declare const rmdir: StepHandler<RmdirStep>;
+/**
+ * @inheritDoc writeFile
+ * @hasRunnableExample
+ * @landingPage /test.php
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "writeFile",
+ * 		"path": "/wordpress/test.php",
+ * 		"data": "<?php echo 'Hello World!'; ?>"
+ * }
+ * </code>
+ */
 export interface WriteFileStep<ResourceType> {
     step: 'writeFile';
     path: string;
     data: ResourceType | string | Uint8Array;
 }
+/**
+ * Writes data to a file at the specified path.
+ */
 export declare const writeFile: StepHandler<WriteFileStep<File>>;

package/lib/steps/handlers.d.ts

@@ -1,4 +1,5 @@
 export { activatePlugin } from './activate-plugin';
+export { activateTheme } from './activate-theme';
 export { applyWordPressPatches } from './apply-wordpress-patches';
 export { rm, cp, mkdir, rmdir, mv, setPhpIniEntry, runPHP, runPHPWithOptions, request, writeFile, } from './client-methods';
 export { defineSiteUrl } from './define-site-url';

package/lib/steps/index.d.ts

@@ -12,6 +12,7 @@ import { RunWpInstallationWizardStep, WordPressInstallationOptions } from './run
 import { SetSiteOptionsStep, UpdateUserMetaStep } from './site-data';
 import { RmStep, CpStep, MkdirStep, RmdirStep, MvStep, SetPhpIniEntryStep, RunPHPStep, RunPHPWithOptionsStep, RequestStep, WriteFileStep } from './client-methods';
 import { DefineWpConfigConstsStep } from './define-wp-config-consts';
+import { ActivateThemeStep } from './activate-theme';
 import { DefineVirtualWpConfigConstsStep } from './define-virtual-wp-config-consts';
 export type Step = GenericStep<FileReference>;
 export type StepDefinition = Step & {
@@ -20,9 +21,21 @@ export type StepDefinition = Step & {
         caption?: string;
     };
 };
-export type GenericStep<Resource> = ActivatePluginStep | ApplyWordPressPatchesStep | CpStep | DefineWpConfigConstsStep | DefineVirtualWpConfigConstsStep | DefineSiteUrlStep | ImportFileStep<Resource> | InstallPluginStep<Resource> | InstallThemeStep<Resource> | LoginStep | MkdirStep | MvStep | RequestStep | ReplaceSiteStep<Resource> | RmStep | RmdirStep | RunPHPStep | RunPHPWithOptionsStep | RunWpInstallationWizardStep | SetPhpIniEntryStep | SetSiteOptionsStep | UnzipStep | UpdateUserMetaStep | WriteFileStep<Resource>;
-export type { ActivatePluginStep, ApplyWordPressPatchesStep, CpStep, DefineWpConfigConstsStep, DefineSiteUrlStep, ImportFileStep, InstallPluginStep, InstallPluginOptions, InstallThemeStep, InstallThemeOptions, LoginStep, MkdirStep, MvStep, RequestStep, ReplaceSiteStep, RmStep, RmdirStep, RunPHPStep, RunPHPWithOptionsStep, RunWpInstallationWizardStep, WordPressInstallationOptions, SetPhpIniEntryStep, SetSiteOptionsStep, UnzipStep, UpdateUserMetaStep, WriteFileStep, };
-export type StepHandler<S extends GenericStep<File>> = (php: UniversalPHP, args: Omit<S, 'step'>, progressArgs?: {
+/**
+ * If you add a step here, make sure to also
+ * add it to the exports below.
+ */
+export type GenericStep<Resource> = ActivatePluginStep | ActivateThemeStep | ApplyWordPressPatchesStep | CpStep | DefineWpConfigConstsStep | DefineVirtualWpConfigConstsStep | DefineSiteUrlStep | ImportFileStep<Resource> | InstallPluginStep<Resource> | InstallThemeStep<Resource> | LoginStep | MkdirStep | MvStep | RequestStep | ReplaceSiteStep<Resource> | RmStep | RmdirStep | RunPHPStep | RunPHPWithOptionsStep | RunWpInstallationWizardStep | SetPhpIniEntryStep | SetSiteOptionsStep | UnzipStep | UpdateUserMetaStep | WriteFileStep<Resource>;
+export type { ActivatePluginStep, ActivateThemeStep, ApplyWordPressPatchesStep, CpStep, DefineWpConfigConstsStep, DefineVirtualWpConfigConstsStep, DefineSiteUrlStep, ImportFileStep, InstallPluginStep, InstallPluginOptions, InstallThemeStep, InstallThemeOptions, LoginStep, MkdirStep, MvStep, RequestStep, ReplaceSiteStep, RmStep, RmdirStep, RunPHPStep, RunPHPWithOptionsStep, RunWpInstallationWizardStep, WordPressInstallationOptions, SetPhpIniEntryStep, SetSiteOptionsStep, UnzipStep, UpdateUserMetaStep, WriteFileStep, };
+export type StepHandler<S extends GenericStep<File>> = (
+/**
+ * A PHP instance or Playground client.
+ */
+php: UniversalPHP, args: Omit<S, 'step'>, 
+/**
+ * Progress reporting details.
+ */
+progressArgs?: {
     tracker: ProgressTracker;
     initialCaption?: string;
 }) => any;

package/lib/steps/install-plugin.d.ts

@@ -1,13 +1,18 @@
 import { StepHandler } from '.';
 /**
- * The step to install a WordPress plugin in the Playground.
- *
+ * @inheritDoc installPlugin
+ * @hasRunnableExample
+ * @needsLogin
+ * @landingPage /wp-admin/plugins.php
  * @example
  *
  * <code>
  * {
  * 	    "step": "installPlugin",
- * 		"pluginZipFile": "http://example.com/plugin.zip",
+ * 		"pluginZipFile": {
+ * 			"resource": "wordpress.org/plugins",
+ * 			"slug": "gutenberg"
+ * 		},
  * 		"options": {
  * 			"activate": true
  * 		}

package/lib/steps/install-theme.d.ts

@@ -1,8 +1,41 @@
 import { StepHandler } from '.';
+/**
+ * @inheritDoc installTheme
+ * @hasRunnableExample
+ * @needsLogin
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "installTheme",
+ * 		"themeZipFile": {
+ * 			"resource": "wordpress.org/themes",
+ * 			"slug": "pendant"
+ * 		},
+ * 		"options": {
+ * 			"activate": true
+ * 		}
+ * }
+ * </code>
+ */
 export interface InstallThemeStep<ResourceType> {
+    /**
+     * The step identifier.
+     */
     step: 'installTheme';
+    /**
+     * The theme zip file to install.
+     */
     themeZipFile: ResourceType;
-    options?: InstallThemeOptions;
+    /**
+     * Optional installation options.
+     */
+    options?: {
+        /**
+         * Whether to activate the theme after installing it.
+         */
+        activate?: boolean;
+    };
 }
 export interface InstallThemeOptions {
     /**

package/lib/steps/login.d.ts

@@ -1,16 +1,31 @@
 import { StepHandler } from '.';
+/**
+ * @inheritDoc login
+ * @hasRunnableExample
+ * @example
+ *
+ * <code>
+ * {
+ * 	    "step": "login",
+ * 		"username": "admin",
+ * 		"password": "password"
+ * }
+ * </code>
+ */
 export type LoginStep = {
     step: 'login';
+    /**
+     * The user to log in as. Defaults to 'admin'.
+     */
     username?: string;
+    /**
+     * The password to log in with. Defaults to 'password'.
+     */
     password?: string;
 };
 /**
  * Logs in to the Playground.
  * Under the hood, this function submits the wp-login.php form
  * just like a user would.
- *
- * @param playground The playground client.
- * @param user The user to log in as. Defaults to 'admin'.
- * @param password The password to log in with. Defaults to 'password'.
  */
 export declare const login: StepHandler<LoginStep>;

package/lib/steps/site-data.d.ts

@@ -1,12 +1,55 @@
 import { StepHandler } from '.';
+/**
+ * @inheritDoc setSiteOptions
+ * @hasRunnableExample
+ *
+ * @example
+ *
+ * <code>
+ * {
+ *     "step": "setSiteOptions",
+ *     "options": {
+ *         "blogname": "My Blog",
+ *         "blogdescription": "A great blog"
+ *     }
+ * }
+ * </code>
+ */
 export type SetSiteOptionsStep = {
+    /** The name of the step. Must be "setSiteOptions". */
     step: 'setSiteOptions';
+    /** The options to set on the site. */
     options: Record<string, unknown>;
 };
+/**
+ * Sets site options. This is equivalent to calling `update_option` for each
+ * option in the `options` object.
+ */
 export declare const setSiteOptions: StepHandler<SetSiteOptionsStep>;
+/**
+ * @inheritDoc updateUserMeta
+ * @hasRunnableExample
+ *
+ * @example
+ *
+ * <code>
+ * {
+ *     "step": "updateUserMeta",
+ *     "meta": {
+ * 	       "first_name": "John",
+ * 	       "last_name": "Doe"
+ *     },
+ *     "userId": 1
+ * }
+ * </code>
+ */
 export interface UpdateUserMetaStep {
     step: 'updateUserMeta';
     meta: Record<string, unknown>;
     userId: number;
 }
+/**
+ * Updates user meta. This is equivalent to calling `update_user_meta` for each
+ * meta value in the `meta` object.
+ */
 export declare const updateUserMeta: StepHandler<UpdateUserMetaStep>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wp-playground/blueprints",
-	"version": "0.1.45",
+	"version": "0.1.49",
 	"exports": {
 		".": {
 			"import": "./index.js",
@@ -21,5 +21,5 @@
 		"access": "public",
 		"directory": "../../../dist/packages/playground/blueprints"
 	},
-	"gitHead": "ca75514c17b912dc8b5dc529f6d123295671320a"
+	"gitHead": "93834fa77a89c21be2ade4c1d67430981ed92c83"
 }