@dream-encode/wp-js-plugin-utils 0.1.0

package/dist/settings/AdminSettingsPage.js

@@ -0,0 +1,86 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _components = require("@wordpress/components");
+var _element = require("@wordpress/element");
+var _i18n = require("@wordpress/i18n");
+var _Notices = _interopRequireDefault(require("../components/Notices"));
+var _jsxRuntime = require("react/jsx-runtime");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * Generic admin settings page shell.
+ *
+ * Renders a header, loading placeholder, notices, body content, and a
+ * standard "Save" button wired to the `useSettings`-style API.
+ *
+ * @param  {Object}    props
+ * @param  {string}    props.title           Page title.
+ * @param  {string}    [props.appVersion]    Optional app version to display in the header.
+ * @param  {Object}    props.settings        Object returned from a `useSettings` hook (must expose `settingsLoaded`, `settingsSaving`, `saveSettings`).
+ * @param  {Function}  [props.onSave]        Optional override for the save handler.
+ * @param  {string}    [props.textDomain]    Text domain for translated UI strings.
+ * @param  {Function}  props.children        Render-prop receiving `settings` to render the form body.
+ * @return {JSX.Element}
+ */const AdminSettingsPage = ({
+  title,
+  appVersion,
+  settings,
+  onSave,
+  textDomain = 'default',
+  children
+}) => {
+  const {
+    settingsLoaded,
+    settingsSaving,
+    saveSettings
+  } = settings;
+  const handleSave = async event => {
+    event.preventDefault();
+    if (typeof onSave === 'function') {
+      await onSave(event);
+      return;
+    }
+    await saveSettings();
+  };
+  return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_element.Fragment, {
+    children: [/*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
+      className: "settings-header",
+      children: /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
+        className: "settings-container",
+        children: /*#__PURE__*/(0, _jsxRuntime.jsxs)("div", {
+          className: "settings-logo",
+          children: [/*#__PURE__*/(0, _jsxRuntime.jsx)("h1", {
+            children: title
+          }), appVersion && /*#__PURE__*/(0, _jsxRuntime.jsxs)(_components.__experimentalText, {
+            className: "version",
+            variant: "muted",
+            children: ["(v", appVersion, ")"]
+          })]
+        })
+      })
+    }), /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
+      className: "settings-main",
+      children: !settingsLoaded ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_components.Placeholder, {
+        children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_components.Spinner, {})
+      }) : /*#__PURE__*/(0, _jsxRuntime.jsxs)(_element.Fragment, {
+        children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_Notices.default, {}), typeof children === 'function' ? children(settings) : children, /*#__PURE__*/(0, _jsxRuntime.jsx)(_components.__experimentalHStack, {
+          alignment: "center",
+          children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_components.Button, {
+            variant: "primary",
+            isBusy: settingsSaving,
+            disabled: !settingsLoaded || settingsSaving,
+            isLarge: true,
+            target: "_blank",
+            href: "#",
+            onClick: handleSave,
+            children: settingsSaving ? (0, _i18n.__)('Saving...', textDomain) : (0, _i18n.__)('Save', textDomain)
+          })
+        })]
+      })
+    })]
+  });
+};
+var _default = exports.default = AdminSettingsPage;

package/dist/settings/createUseSettings.js

@@ -0,0 +1,118 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _i18n = require("@wordpress/i18n");
+var _element = require("@wordpress/element");
+var _apiFetch = _interopRequireDefault(require("@wordpress/api-fetch"));
+var _data = require("@wordpress/data");
+var _notices = require("@wordpress/notices");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * Create a `useSettings` hook for a plugin.
+ *
+ * Reads/writes settings via the WordPress core REST settings endpoint
+ * (`/wp/v2/settings`), keyed by `optionName`. Each entry in `fields`
+ * defines a field with `key` (option key), optional `defaultValue`, and
+ * optional state name overrides.
+ *
+ * @param  {Object}   config                Hook configuration.
+ * @param  {string}   config.optionName     Top-level option key on the settings endpoint.
+ * @param  {Array}    config.fields         Field definitions: `{ key, defaultValue, stateName, setterName }`.
+ * @param  {string}   [config.textDomain]   Text domain for translated notice strings.
+ * @param  {string}   [config.path]         REST path (default: '/wp/v2/settings').
+ * @return {Function}                       A `useSettings` React hook.
+ */
+const createUseSettings = config => {
+  const {
+    optionName,
+    fields = [],
+    textDomain = 'default',
+    path = '/wp/v2/settings'
+  } = config;
+  if (!optionName) {
+    throw new Error('[wp-plugin-utils] createUseSettings: "optionName" is required.');
+  }
+  const toCamel = key => key.replace(/[_-](.)/g, (_m, c) => c.toUpperCase());
+  const ucFirst = s => s.charAt(0).toUpperCase() + s.slice(1);
+  return function useSettings() {
+    const {
+      createSuccessNotice,
+      createErrorNotice
+    } = (0, _data.useDispatch)(_notices.store);
+    const [settingsLoaded, updateSettingsLoaded] = (0, _element.useState)(false);
+    const [settingsSaving, updateSettingsSaving] = (0, _element.useState)(false);
+    const initialState = {};
+    fields.forEach(field => {
+      const stateName = field.stateName || toCamel(field.key);
+      initialState[stateName] = field.defaultValue !== undefined ? field.defaultValue : '';
+    });
+    const [values, setValues] = (0, _element.useState)(initialState);
+    const setField = stateName => value => {
+      setValues(prev => ({
+        ...prev,
+        [stateName]: value
+      }));
+    };
+    (0, _element.useEffect)(() => {
+      (0, _apiFetch.default)({
+        path
+      }).then(settings => {
+        const optionData = settings[optionName] || {};
+        const next = {
+          ...initialState
+        };
+        fields.forEach(field => {
+          const stateName = field.stateName || toCamel(field.key);
+          if (optionData[field.key] !== undefined) {
+            next[stateName] = optionData[field.key];
+          }
+        });
+        setValues(next);
+        updateSettingsLoaded(true);
+      });
+    }, []);
+    const saveSettings = async () => {
+      updateSettingsSaving(true);
+      const optionData = {};
+      fields.forEach(field => {
+        const stateName = field.stateName || toCamel(field.key);
+        optionData[field.key] = values[stateName];
+      });
+      const saveResult = await (0, _apiFetch.default)({
+        path,
+        method: 'POST',
+        data: {
+          [optionName]: optionData
+        }
+      });
+      if (!saveResult) {
+        updateSettingsSaving(false);
+        createErrorNotice((0, _i18n.sprintf)(/* translators: %s: Error message. */
+        (0, _i18n.__)('Error saving settings: %s.', textDomain), saveResult?.message ?? (0, _i18n.__)('Unknown error', textDomain)));
+        return;
+      }
+      updateSettingsSaving(false);
+      createSuccessNotice((0, _i18n.__)('Settings saved.', textDomain));
+    };
+    const exposed = {
+      settingsLoaded,
+      updateSettingsLoaded,
+      settingsSaving,
+      updateSettingsSaving,
+      values,
+      setValues,
+      saveSettings
+    };
+    fields.forEach(field => {
+      const stateName = field.stateName || toCamel(field.key);
+      const setterName = field.setterName || `update${ucFirst(stateName)}`;
+      exposed[stateName] = values[stateName];
+      exposed[setterName] = setField(stateName);
+    });
+    return exposed;
+  };
+};
+var _default = exports.default = createUseSettings;

package/dist/settings/index.js

@@ -0,0 +1,20 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "AdminSettingsPage", {
+  enumerable: true,
+  get: function () {
+    return _AdminSettingsPage.default;
+  }
+});
+Object.defineProperty(exports, "createUseSettings", {
+  enumerable: true,
+  get: function () {
+    return _createUseSettings.default;
+  }
+});
+var _createUseSettings = _interopRequireDefault(require("./createUseSettings"));
+var _AdminSettingsPage = _interopRequireDefault(require("./AdminSettingsPage"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }

package/dist/settings/styles/_settings-page.scss

@@ -0,0 +1,124 @@
+/*
+ * Generic styling for the wp-plugin-utils AdminSettingsPage shell.
+ *
+ * Wrap with the WordPress settings page selector for the plugin, e.g.:
+ *
+ *     .settings_page_my-plugin-settings {
+ *         @include de-wp-plugin-utils-settings-page;
+ *     }
+ */
+
+@mixin de-wp-plugin-utils-settings-page {
+	background: #f6f6f6;
+	position: relative;
+	box-sizing: border-box;
+
+	.components-placeholder {
+		background: #FFFFFF;
+		margin-top: 25px;
+		border: 1px solid #e2e4e7;
+		box-shadow: none;
+
+		.components-placeholder__fieldset {
+			justify-content: center;
+		}
+	}
+
+	.settings-header {
+		padding: 20px 10px;
+		background-color: #ffffff;
+		box-shadow: 0 1px 0 rgba(213, 213, 213, 0.5), 0 1px 2px #eee;
+
+		.settings-container {
+			margin: 0 auto;
+			max-width: 900px;
+
+			.settings-logo {
+				display: flex;
+				flex-direction: column;
+				align-items: center;
+				justify-content: center;
+
+				h1 {
+					display: flex;
+					flex-direction: row;
+					align-items: center;
+					justify-content: center;
+					margin: 0.6rem;
+				}
+
+				.version {
+					font-size: 12px;
+				}
+			}
+		}
+	}
+
+	.settings-main {
+		margin-left: auto;
+		margin-right: auto;
+		max-width: 1440px;
+
+		.components-panel__body {
+			margin: 25px 0;
+			background: #fff;
+			border: 1px solid #e2e4e7;
+
+			.components-panel__body-toggle {
+				border-bottom: 1px solid #d6e2ed;
+			}
+
+			.field-divider {
+				border-color: #cbd5e1;
+			}
+
+			.components-panel__row {
+				margin: 0;
+				width: 100%;
+
+				&.field-row {
+					padding: 1.0rem 0;
+
+					.components-base-control {
+						width: 100%;
+					}
+
+					.checkbox-group {
+						margin-left: 1.0rem;
+					}
+				}
+
+				&.buttons-row {
+					justify-content: center;
+				}
+			}
+		}
+
+		.settings-info {
+			padding: 0 10px 10px;
+
+			h2 {
+				font-weight: 300;
+				margin-bottom: 10px;
+			}
+
+			p {
+				margin: 0 0 1.5em 0;
+			}
+
+			.settings-info-button-group {
+				display: flex;
+
+				.is-default {
+					padding: 2px 20px;
+					height: auto;
+					font-size: 14px;
+
+					&:first-child {
+						margin-right: 15px;
+					}
+				}
+			}
+		}
+	}
+}

package/dist/utils/constants.js

@@ -0,0 +1,12 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.SHOW_MIGRATION_ID_IN_PREVIOUS_MIGRATIONS_SELECT = exports.SHOW_CANCEL_ALL_MIGRATIONS_BUTTON = exports.MIGRATION_RESULTS_PER_PAGE = exports.MIGRATION_ACTION_SCHEDULER_QUEUE_MODE = exports.LOG_LEVELS = exports.ALERTS_TIMEOUT = void 0;
+const ALERTS_TIMEOUT = exports.ALERTS_TIMEOUT = 10000;
+const MIGRATION_RESULTS_PER_PAGE = exports.MIGRATION_RESULTS_PER_PAGE = 100;
+const SHOW_CANCEL_ALL_MIGRATIONS_BUTTON = exports.SHOW_CANCEL_ALL_MIGRATIONS_BUTTON = false;
+const SHOW_MIGRATION_ID_IN_PREVIOUS_MIGRATIONS_SELECT = exports.SHOW_MIGRATION_ID_IN_PREVIOUS_MIGRATIONS_SELECT = false;
+const LOG_LEVELS = exports.LOG_LEVELS = ['emergency', 'alert', 'critical', 'error', 'warning', 'notice', 'info', 'debug', 'off'];
+const MIGRATION_ACTION_SCHEDULER_QUEUE_MODE = exports.MIGRATION_ACTION_SCHEDULER_QUEUE_MODE = ['async', 'scheduled'];

package/dist/utils/dates.js

@@ -0,0 +1,82 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.convertUTCMySQLDateTimeToLocalTime = exports.convertUTCMySQLDateTimeToLocalDateTime = exports.convertTimestampToFriendlyTime = exports.convertTimestampToFriendlyDate = void 0;
+var _i18n = require("@wordpress/i18n");
+/**
+ * Convert a timestamp to a human readable date format, using toLocaleString.
+ *
+ * @param  {number|string}  timestamp  Unix timestamp (seconds).
+ * @param  {string}         [textDomain='default']
+ * @return {string}
+ */
+const convertTimestampToFriendlyDate = (timestamp, textDomain = 'default') => {
+  if (!timestamp) {
+    return (0, _i18n.__)('N/A', textDomain);
+  }
+  const date = new Date(Number(timestamp) * 1000);
+  const options = {
+    dateStyle: 'full',
+    timeStyle: 'short'
+  };
+  return date.toLocaleString(undefined, options);
+};
+
+/**
+ * Convert a timestamp to a human readable time format, using toLocaleTimeString.
+ *
+ * @param  {number}  timestamp  Unix timestamp (seconds).
+ * @param  {string}  [textDomain='default']
+ * @return {string}
+ */
+exports.convertTimestampToFriendlyDate = convertTimestampToFriendlyDate;
+const convertTimestampToFriendlyTime = (timestamp, textDomain = 'default') => {
+  if (!timestamp) {
+    return (0, _i18n.__)('N/A', textDomain);
+  }
+  const date = new Date(timestamp * 1000);
+  const options = {
+    timeStyle: 'short'
+  };
+  return date.toLocaleTimeString(undefined, options);
+};
+
+/**
+ * Convert a UTC MySQL DateTime to a local date time.
+ *
+ * @param  {string}  utcDateTime  UTC MySQL DateTime.
+ * @return {string}
+ */
+exports.convertTimestampToFriendlyTime = convertTimestampToFriendlyTime;
+const convertUTCMySQLDateTimeToLocalDateTime = utcDateTime => {
+  if (!utcDateTime) {
+    return '';
+  }
+  const localDate = new Date(utcDateTime + 'Z');
+  const options = {
+    dateStyle: 'full',
+    timeStyle: 'short'
+  };
+  return localDate.toLocaleString(undefined, options);
+};
+
+/**
+ * Convert a UTC MySQL DateTime to a local time.
+ *
+ * @param  {string}  utcDateTime  UTC MySQL DateTime.
+ * @return {string}
+ */
+exports.convertUTCMySQLDateTimeToLocalDateTime = convertUTCMySQLDateTimeToLocalDateTime;
+const convertUTCMySQLDateTimeToLocalTime = utcDateTime => {
+  if (!utcDateTime) {
+    return '';
+  }
+  const localDate = new Date(utcDateTime + 'Z');
+  const options = {
+    timeStyle: 'short'
+  };
+  return localDate.toLocaleTimeString(undefined, options);
+};
+exports.convertUTCMySQLDateTimeToLocalTime = convertUTCMySQLDateTimeToLocalTime;

package/dist/utils/index.js

@@ -0,0 +1,60 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+var _constants = require("./constants");
+Object.keys(_constants).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _constants[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _constants[key];
+    }
+  });
+});
+var _strings = require("./strings");
+Object.keys(_strings).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _strings[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _strings[key];
+    }
+  });
+});
+var _time = require("./time");
+Object.keys(_time).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _time[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _time[key];
+    }
+  });
+});
+var _dates = require("./dates");
+Object.keys(_dates).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _dates[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _dates[key];
+    }
+  });
+});
+var _wp = require("./wp");
+Object.keys(_wp).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _wp[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _wp[key];
+    }
+  });
+});

package/dist/utils/strings.js

@@ -0,0 +1,41 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.zeroPadNumber = exports.trimTrailingSlash = exports.capitalizeFirstLetter = void 0;
+/**
+ * Capitalize the first letter of every word.
+ *
+ * @param  {string}  string  String.
+ * @return {string}
+ */
+const capitalizeFirstLetter = string => {
+  return string.toLowerCase().replace(/\b[a-z]/g, letter => {
+    return letter.toUpperCase();
+  });
+};
+
+/**
+ * Trim the trailing slash from a string.
+ *
+ * @param  {string}  string  String.
+ * @return {string}
+ */
+exports.capitalizeFirstLetter = capitalizeFirstLetter;
+const trimTrailingSlash = string => {
+  return string.replace(/\/$/, '');
+};
+
+/**
+ * Add leading zeroes to a number.
+ *
+ * @param  {number}  num     Number.
+ * @param  {number}  places  Total places.
+ * @return {string}
+ */
+exports.trimTrailingSlash = trimTrailingSlash;
+const zeroPadNumber = (num, places) => {
+  return String(num).padStart(places, '0');
+};
+exports.zeroPadNumber = zeroPadNumber;

package/dist/utils/time.js

@@ -0,0 +1,83 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.secondsToDhmsShortIso = exports.secondsToDhmsShort = exports.secondsToDhms = exports.addSecondsToCurrentTime = void 0;
+var _strings = require("./strings");
+/**
+ * Convert seconds to a human readable format.
+ * Example: "3 days, 11 hours, 2 minutes, 58 seconds".
+ *
+ * @param  {number}  seconds  Seconds remaining.
+ * @return {string|false}
+ */
+const secondsToDhms = seconds => {
+  if (seconds <= 0) {
+    return false;
+  }
+  seconds = Number(seconds);
+  const d = Math.floor(seconds / (3600 * 24));
+  const h = Math.floor(seconds % (3600 * 24) / 3600);
+  const m = Math.floor(seconds % 3600 / 60);
+  const s = Math.floor(seconds % 60);
+  const dDisplay = d > 0 ? d + (1 === d ? ' day, ' : ' days, ') : '';
+  const hDisplay = h > 0 ? h + (1 === h ? ' hour, ' : ' hours, ') : '';
+  const mDisplay = m > 0 ? m + (1 === m ? ' minute, ' : ' minutes, ') : '';
+  const sDisplay = s > 0 ? s + (1 === s ? ' second' : ' seconds') : '';
+  return dDisplay + hDisplay + mDisplay + sDisplay;
+};
+
+/**
+ * Convert seconds to a human readable format, using toISOString.
+ * Example: "2:58".
+ *
+ * @param  {number}  seconds  Seconds remaining.
+ * @return {string|false}
+ */
+exports.secondsToDhms = secondsToDhms;
+const secondsToDhmsShortIso = seconds => {
+  if (seconds <= 0) {
+    return false;
+  }
+  if (seconds < 3600) {
+    return new Date(seconds * 1000).toISOString().substring(14, 19);
+  }
+  return new Date(seconds * 1000).toISOString().substring(11, 16);
+};
+
+/**
+ * Convert seconds to a human readable format, but a bit shorter.
+ * Example: "11:02:59".
+ *
+ * @param  {number}  seconds  Seconds remaining.
+ * @return {string|false}
+ */
+exports.secondsToDhmsShortIso = secondsToDhmsShortIso;
+const secondsToDhmsShort = seconds => {
+  if (seconds <= 0) {
+    return false;
+  }
+  seconds = Number(seconds);
+  const h = Math.floor(seconds % (3600 * 24) / 3600);
+  const m = Math.floor(seconds % 3600 / 60);
+  const s = Math.floor(seconds % 60);
+  const hDisplay = h > 0 ? h + ':' : '';
+  const mDisplay = h > 0 ? (0, _strings.zeroPadNumber)(m, 2) + ':' : m > 0 ? m + ':' : (0, _strings.zeroPadNumber)(m, 1) + ':';
+  const sDisplay = seconds > 0 ? (0, _strings.zeroPadNumber)(s, 2) : '';
+  return hDisplay + mDisplay + sDisplay;
+};
+
+/**
+ * Add a number of seconds to the current time.
+ *
+ * @param  {number}  seconds  Seconds to add.
+ * @return {number}
+ */
+exports.secondsToDhmsShort = secondsToDhmsShort;
+const addSecondsToCurrentTime = seconds => {
+  let rawDate = new Date();
+  rawDate = new Date(rawDate.getTime() + Number(seconds * 1000));
+  return rawDate.getTime() / 1000;
+};
+exports.addSecondsToCurrentTime = addSecondsToCurrentTime;

package/dist/utils/wp.js

@@ -0,0 +1,35 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.wpEditPostLinkFromPostId = exports.getAdminPageUrl = void 0;
+var _url = require("@wordpress/url");
+/**
+ * Get a URL to edit a post with a post ID.
+ *
+ * @param  {number}  postID    Post ID.
+ * @param  {string}  adminUrl  WP admin URL (with trailing slash).
+ * @return {string}
+ */
+const wpEditPostLinkFromPostId = (postID, adminUrl) => {
+  return (0, _url.addQueryArgs)(`${adminUrl}post.php`, {
+    post: postID,
+    action: 'edit'
+  });
+};
+
+/**
+ * Build an admin page URL.
+ *
+ * @param  {string}  page          Admin page slug.
+ * @param  {string}  [parent='admin.php']  Parent admin file.
+ * @return {string}
+ */
+exports.wpEditPostLinkFromPostId = wpEditPostLinkFromPostId;
+const getAdminPageUrl = (page, parent = 'admin.php') => {
+  return (0, _url.addQueryArgs)(parent, {
+    page
+  });
+};
+exports.getAdminPageUrl = getAdminPageUrl;