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

package/README.md

@@ -0,0 +1,109 @@
+# @dream-encode/wp-plugin-utils
+
+Common JS functionality used by custom WP plugins.
+
+## Install
+
+```bash
+yarn add @dream-encode/wp-plugin-utils
+```
+
+The package declares `@wordpress/*`, `react`, `webpack`, and the related
+loaders/plugins as peer dependencies. Plugins consuming this package are
+expected to provide their own versions.
+
+## Subpath exports
+
+| Import path                                         | Description                                            |
+| --------------------------------------------------- | ------------------------------------------------------ |
+| `@dream-encode/wp-plugin-utils`                     | All modules grouped under namespaces.                  |
+| `@dream-encode/wp-plugin-utils/webpack`             | `createWebpackConfig` factory (CommonJS).              |
+| `@dream-encode/wp-plugin-utils/postcss`             | Default PostCSS config (CommonJS).                     |
+| `@dream-encode/wp-plugin-utils/settings`            | `createUseSettings`, `AdminSettingsPage`.              |
+| `@dream-encode/wp-plugin-utils/settings/styles`     | SCSS partial with the settings-page styles mixin.      |
+| `@dream-encode/wp-plugin-utils/data-migrations`     | Registry helpers for the Data Migrations plugin.       |
+| `@dream-encode/wp-plugin-utils/components`          | Shared components (`Notices`).                         |
+| `@dream-encode/wp-plugin-utils/hooks`               | `useValueChangeEffect`, `useBlurableContent`, …        |
+| `@dream-encode/wp-plugin-utils/api`                 | `fetchGetOptions`, `fetchPostOptions`.                 |
+| `@dream-encode/wp-plugin-utils/utils`               | Strings, dates, time, WP url helpers.                  |
+| `@dream-encode/wp-plugin-utils/constants`           | Shared constants (`LOG_LEVELS`, …).                    |
+
+## Webpack config
+
+```js
+// webpack.config.js
+const createWebpackConfig = require( '@dream-encode/wp-plugin-utils/webpack' )
+
+module.exports = createWebpackConfig( {
+	context: __dirname,
+	appVersion: require( './package.json' ),
+	sentry: true,
+	entry: {
+		'admin-settings-page': [
+			'./admin/assets/src/js/admin-settings-page.js',
+			'./admin/assets/src/scss/admin-settings-page.scss'
+		]
+	}
+} )
+```
+
+## Settings hook + page shell
+
+```jsx
+import { createUseSettings, AdminSettingsPage } from '@dream-encode/wp-plugin-utils/settings'
+
+const useSettings = createUseSettings( {
+	optionName: 'my_plugin_settings',
+	textDomain: 'my-plugin',
+	fields: [
+		{ key: 'plugin_log_level', defaultValue: 'off' },
+		{ key: 'feature_flag_x', defaultValue: false }
+	]
+} )
+
+const SettingsPage = () => {
+	const settings = useSettings()
+
+	return (
+		<AdminSettingsPage
+			title="My Plugin"
+			appVersion={ APP_VERSION }
+			textDomain="my-plugin"
+			settings={ settings }
+		>
+			{ ( s ) => (
+				/* Render your fields, reading from `s.pluginLogLevel`, etc. */
+				null
+			) }
+		</AdminSettingsPage>
+	)
+}
+```
+
+Use the SCSS mixin to style the page:
+
+```scss
+@use "@dream-encode/wp-plugin-utils/settings/styles" as utils;
+
+.settings_page_my-plugin-settings {
+	@include utils.de-wp-plugin-utils-settings-page;
+}
+```
+
+## Data Migrations registry
+
+```js
+import domReady from '@wordpress/dom-ready'
+import {
+	registerMigratorSettings,
+	registerResultsRenderer
+} from '@dream-encode/wp-plugin-utils/data-migrations'
+
+import MyMigratorSettings from './components/MyMigratorSettings'
+import MyResultsRenderer from './components/MyResultsRenderer'
+
+domReady( () => {
+	registerMigratorSettings( 'my_migrator', MyMigratorSettings )
+	registerResultsRenderer( 'my_migrator', MyResultsRenderer )
+} )
+```

package/dist/api/fetchOptions.js

@@ -0,0 +1,39 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.fetchPostOptions = exports.fetchGetOptions = void 0;
+/**
+ * Build fetch GET options with the WP REST nonce header.
+ *
+ * @param  {string}  nonce  WP REST nonce.
+ * @return {Object}
+ */
+const fetchGetOptions = nonce => {
+  return {
+    headers: {
+      'X-WP-Nonce': nonce
+    }
+  };
+};
+
+/**
+ * Build fetch POST options with the WP REST nonce header.
+ *
+ * @param  {Object}  postData  Body to JSON-encode.
+ * @param  {string}  nonce     WP REST nonce.
+ * @return {Object}
+ */
+exports.fetchGetOptions = fetchGetOptions;
+const fetchPostOptions = (postData, nonce) => {
+  return {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-WP-Nonce': nonce
+    },
+    body: JSON.stringify(postData)
+  };
+};
+exports.fetchPostOptions = fetchPostOptions;

package/dist/api/index.js

@@ -0,0 +1,16 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+var _fetchOptions = require("./fetchOptions");
+Object.keys(_fetchOptions).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _fetchOptions[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _fetchOptions[key];
+    }
+  });
+});

package/dist/components/Notices.js

@@ -0,0 +1,24 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _data = require("@wordpress/data");
+var _notices = require("@wordpress/notices");
+var _components = require("@wordpress/components");
+var _jsxRuntime = require("react/jsx-runtime");
+const Notices = () => {
+  const {
+    removeNotice
+  } = (0, _data.useDispatch)(_notices.store);
+  const notices = (0, _data.useSelect)(select => select(_notices.store).getNotices());
+  if (notices.length === 0) {
+    return null;
+  }
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_components.NoticeList, {
+    notices: notices,
+    onRemove: removeNotice
+  });
+};
+var _default = exports.default = Notices;

package/dist/components/index.js

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

package/dist/data-migrations/index.js

@@ -0,0 +1,50 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "getMigratorRenderer", {
+  enumerable: true,
+  get: function () {
+    return _registry.getMigratorRenderer;
+  }
+});
+Object.defineProperty(exports, "getMigratorSettingsComponent", {
+  enumerable: true,
+  get: function () {
+    return _registry.getMigratorSettingsComponent;
+  }
+});
+Object.defineProperty(exports, "getResultsRenderer", {
+  enumerable: true,
+  get: function () {
+    return _registry.getResultsRenderer;
+  }
+});
+Object.defineProperty(exports, "registerMigratorRenderer", {
+  enumerable: true,
+  get: function () {
+    return _registry.registerMigratorRenderer;
+  }
+});
+Object.defineProperty(exports, "registerMigratorSettings", {
+  enumerable: true,
+  get: function () {
+    return _registry.registerMigratorSettings;
+  }
+});
+Object.defineProperty(exports, "registerOnReady", {
+  enumerable: true,
+  get: function () {
+    return _registerOnReady.default;
+  }
+});
+Object.defineProperty(exports, "registerResultsRenderer", {
+  enumerable: true,
+  get: function () {
+    return _registry.registerResultsRenderer;
+  }
+});
+var _registry = require("./registry");
+var _registerOnReady = _interopRequireDefault(require("./registerOnReady"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }

package/dist/data-migrations/registerOnReady.js

@@ -0,0 +1,36 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _domReady = _interopRequireDefault(require("@wordpress/dom-ready"));
+var _registry = require("./registry");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * Register a batch of Data Migrations extensions on `domReady`.
+ *
+ * @param  {Object}  registrations                       Registration map.
+ * @param  {Object}  [registrations.migratorSettings]    Map of migrator key -> Component.
+ * @param  {Object}  [registrations.resultsRenderers]    Map of renderer key -> Component.
+ * @param  {Object}  [registrations.migratorRenderers]   Map of migrator key -> Component.
+ */
+const registerOnReady = (registrations = {}) => {
+  const {
+    migratorSettings = {},
+    resultsRenderers = {},
+    migratorRenderers = {}
+  } = registrations;
+  (0, _domReady.default)(() => {
+    Object.entries(migratorSettings).forEach(([key, Component]) => {
+      (0, _registry.registerMigratorSettings)(key, Component);
+    });
+    Object.entries(resultsRenderers).forEach(([key, Component]) => {
+      (0, _registry.registerResultsRenderer)(key, Component);
+    });
+    Object.entries(migratorRenderers).forEach(([key, Component]) => {
+      (0, _registry.registerMigratorRenderer)(key, Component);
+    });
+  });
+};
+var _default = exports.default = registerOnReady;

package/dist/data-migrations/registry.js

@@ -0,0 +1,136 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.registerResultsRenderer = exports.registerMigratorSettings = exports.registerMigratorRenderer = exports.getResultsRenderer = exports.getMigratorSettingsComponent = exports.getMigratorRenderer = void 0;
+/**
+ * Lightweight wrappers around the global window registry exposed by
+ * `max-marine-data-migrations`. Provides a typed-ish API for plugins
+ * extending Data Migrations to register migrator settings UIs, custom
+ * migrator renderers, and per-migrator results renderers.
+ *
+ * The Data Migrations plugin is responsible for initializing
+ * `window.maxMarineDataMigrations` and the `register*` functions on it
+ * before any consumer code runs (its admin scripts populate the slot in
+ * a `domReady` handler). These helpers will no-op silently if the host
+ * plugin has not been loaded.
+ */
+
+const NAMESPACE = 'maxMarineDataMigrations';
+const getRegistry = () => {
+  if (typeof window === 'undefined') {
+    return null;
+  }
+  return window[NAMESPACE] || null;
+};
+
+/**
+ * Ensure the registry namespace and a property collection exist on `window`.
+ *
+ * @param  {string}  bucket  Property name to ensure on the registry.
+ * @return {Object|null}
+ */
+const ensureRegistry = bucket => {
+  if (typeof window === 'undefined') {
+    return null;
+  }
+  window[NAMESPACE] = window[NAMESPACE] || {};
+  if (bucket && !window[NAMESPACE][bucket]) {
+    window[NAMESPACE][bucket] = {};
+  }
+  return window[NAMESPACE];
+};
+
+/**
+ * Register a migrator settings React component for a migrator key.
+ *
+ * @param  {string}    migratorKey
+ * @param  {Function}  Component
+ */
+const registerMigratorSettings = (migratorKey, Component) => {
+  const registry = ensureRegistry('migratorSettings');
+  if (!registry) {
+    return;
+  }
+  if (typeof registry.registerMigratorSettings === 'function') {
+    registry.registerMigratorSettings(migratorKey, Component);
+    return;
+  }
+  registry.migratorSettings[migratorKey] = Component;
+};
+
+/**
+ * Register a results renderer React component for a migrator key.
+ *
+ * @param  {string}    rendererKey
+ * @param  {Function}  Component
+ */
+exports.registerMigratorSettings = registerMigratorSettings;
+const registerResultsRenderer = (rendererKey, Component) => {
+  const registry = ensureRegistry('resultsRenderers');
+  if (!registry) {
+    return;
+  }
+  if (typeof registry.registerResultsRenderer === 'function') {
+    registry.registerResultsRenderer(rendererKey, Component);
+    return;
+  }
+  registry.resultsRenderers[rendererKey] = Component;
+};
+
+/**
+ * Register a custom migrator renderer React component for a migrator key.
+ *
+ * @param  {string}    migratorKey
+ * @param  {Function}  Component
+ */
+exports.registerResultsRenderer = registerResultsRenderer;
+const registerMigratorRenderer = (migratorKey, Component) => {
+  const registry = ensureRegistry('migratorRenderers');
+  if (!registry) {
+    return;
+  }
+  if (typeof registry.registerMigratorRenderer === 'function') {
+    registry.registerMigratorRenderer(migratorKey, Component);
+    return;
+  }
+  registry.migratorRenderers[migratorKey] = Component;
+};
+
+/**
+ * Get the registered settings component for a migrator, if any.
+ *
+ * @param  {string}  migratorKey
+ * @return {Function|null}
+ */
+exports.registerMigratorRenderer = registerMigratorRenderer;
+const getMigratorSettingsComponent = migratorKey => {
+  const registry = getRegistry();
+  return registry?.migratorSettings?.[migratorKey] || null;
+};
+
+/**
+ * Get the registered results renderer for a migrator, if any.
+ *
+ * @param  {string}  rendererKey
+ * @return {Function|null}
+ */
+exports.getMigratorSettingsComponent = getMigratorSettingsComponent;
+const getResultsRenderer = rendererKey => {
+  const registry = getRegistry();
+  return registry?.resultsRenderers?.[rendererKey] || null;
+};
+
+/**
+ * Get the registered custom migrator renderer for a migrator, if any.
+ *
+ * @param  {string}  migratorKey
+ * @return {Function|null}
+ */
+exports.getResultsRenderer = getResultsRenderer;
+const getMigratorRenderer = migratorKey => {
+  const registry = getRegistry();
+  return registry?.migratorRenderers?.[migratorKey] || null;
+};
+exports.getMigratorRenderer = getMigratorRenderer;

package/dist/hooks/index.js

@@ -0,0 +1,27 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "useBlurableContent", {
+  enumerable: true,
+  get: function () {
+    return _useBlurableContent.default;
+  }
+});
+Object.defineProperty(exports, "useDebouncedValue", {
+  enumerable: true,
+  get: function () {
+    return _useDebouncedValue.default;
+  }
+});
+Object.defineProperty(exports, "useValueChangeEffect", {
+  enumerable: true,
+  get: function () {
+    return _useValueChangeEffect.default;
+  }
+});
+var _useValueChangeEffect = _interopRequireDefault(require("./useValueChangeEffect"));
+var _useBlurableContent = _interopRequireDefault(require("./useBlurableContent"));
+var _useDebouncedValue = _interopRequireDefault(require("./useDebouncedValue"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }

package/dist/hooks/useBlurableContent.js

@@ -0,0 +1,19 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+/**
+ * Custom hook for managing blurable content.
+ *
+ * @param  {boolean}  isBlurred  Whether the content should be blurred.
+ * @return {Object}              Object containing the blur class and state.
+ */
+const useBlurableContent = isBlurred => {
+  return {
+    blurClass: isBlurred ? 'blurred' : '',
+    isBlurred
+  };
+};
+var _default = exports.default = useBlurableContent;

package/dist/hooks/useDebouncedValue.js

@@ -0,0 +1,33 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _element = require("@wordpress/element");
+/**
+ * Debounce a rapidly-changing value.
+ *
+ * @param  {*}       value     The value to debounce.
+ * @param  {number}  [delay]   Debounce delay in milliseconds.
+ * @return {*}
+ */
+const useDebouncedValue = (value, delay = 300) => {
+  const [debounced, setDebounced] = (0, _element.useState)(value);
+  const timeoutRef = (0, _element.useRef)(null);
+  (0, _element.useEffect)(() => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+    }
+    timeoutRef.current = setTimeout(() => {
+      setDebounced(value);
+    }, delay);
+    return () => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+      }
+    };
+  }, [value, delay]);
+  return debounced;
+};
+var _default = exports.default = useDebouncedValue;

package/dist/hooks/useValueChangeEffect.js

@@ -0,0 +1,74 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _element = require("@wordpress/element");
+/**
+ * Custom hook to create a fade effect when a value changes.
+ *
+ * @param  {*}       value  The value to watch for changes.
+ * @param  {string}  speed  Animation speed: 'default', 'fast', or 'slow' (default: 'default').
+ * @return {Object}         Object containing displayValue, ref to attach to the element, and isAnimating state.
+ */
+const useValueChangeEffect = (value, speed = 'default') => {
+  const stringValue = value === null || value === undefined ? '' : typeof value === 'object' ? JSON.stringify(value) : String(value);
+  const elementRef = (0, _element.useRef)(null);
+  const [prevValue, setPrevValue] = (0, _element.useState)(stringValue);
+  const [displayValue, setDisplayValue] = (0, _element.useState)(stringValue);
+  const [isAnimating, setIsAnimating] = (0, _element.useState)(false);
+  const getDuration = () => {
+    switch (speed) {
+      case 'fast':
+        return 200;
+      case 'slow':
+        return 600;
+      default:
+        return 400;
+    }
+  };
+  const getClassSuffix = () => {
+    switch (speed) {
+      case 'fast':
+        return '-fast';
+      case 'slow':
+        return '-slow';
+      default:
+        return '';
+    }
+  };
+  const duration = getDuration();
+  const classSuffix = getClassSuffix();
+  (0, _element.useEffect)(() => {
+    const newStringValue = value === null || value === undefined ? '' : typeof value === 'object' ? JSON.stringify(value) : String(value);
+    if (newStringValue !== prevValue && elementRef.current && !isAnimating) {
+      setIsAnimating(true);
+      elementRef.current.classList.add(`fade-out${classSuffix}`);
+      setTimeout(() => {
+        setDisplayValue(newStringValue);
+        if (elementRef.current) {
+          elementRef.current.classList.remove(`fade-out${classSuffix}`);
+          void elementRef.current.offsetWidth;
+          elementRef.current.classList.add(`fade-in${classSuffix}`);
+          setTimeout(() => {
+            if (elementRef.current) {
+              elementRef.current.classList.remove(`fade-in${classSuffix}`);
+            }
+            setIsAnimating(false);
+            setPrevValue(newStringValue);
+          }, duration);
+        }
+      }, duration);
+    } else if (newStringValue !== prevValue && !isAnimating) {
+      setDisplayValue(newStringValue);
+      setPrevValue(newStringValue);
+    }
+  }, [value, prevValue, isAnimating, duration, classSuffix]);
+  return {
+    displayValue,
+    elementRef,
+    isAnimating
+  };
+};
+var _default = exports.default = useValueChangeEffect;

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.utils = exports.settings = exports.hooks = exports.dataMigrations = exports.components = exports.api = void 0;
+var _api = _interopRequireWildcard(require("./api"));
+exports.api = _api;
+var _components = _interopRequireWildcard(require("./components"));
+exports.components = _components;
+var _dataMigrations = _interopRequireWildcard(require("./data-migrations"));
+exports.dataMigrations = _dataMigrations;
+var _hooks = _interopRequireWildcard(require("./hooks"));
+exports.hooks = _hooks;
+var _settings = _interopRequireWildcard(require("./settings"));
+exports.settings = _settings;
+var _utils = _interopRequireWildcard(require("./utils"));
+exports.utils = _utils;
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }