@dream-encode/wp-js-plugin-utils 0.6.2 → 0.8.0

package/dist/edit-product/constants.js

@@ -0,0 +1,29 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.SEVERITY_WARN = exports.SEVERITY_BLOCK = exports.EVENT_STOCK_CHANGED = exports.EVENT_SAVE_REQUESTED = exports.EVENT_SAVE_COMMITTED = exports.EVENT_SAVE_BLOCKED = exports.EVENT_RELISTING_DETECTED = exports.EVENT_RELISTING_CONFIRMED = exports.EVENT_RELISTING_CANCELLED = exports.EVENT_PRODUCT_READY = exports.EVENT_DUPLICATE_AWAITING_FIRST_SAVE = exports.EDIT_PRODUCT_STORE_NAME = exports.CONTEXT_RELISTING = exports.CONTEXT_DUPLICATE = exports.CONTEXT_ALWAYS = void 0;
+/**
+ * Lifecycle event names and context values emitted by the edit product kernel.
+ *
+ * These mirror the constants in `max-marine-edit-product-shared-state`. Consumers import
+ * them from here so no plugin hand-copies an event string - which is exactly how
+ * `MMEPSSStockQuantityChanged` ended up declared by hand in two plugins at once.
+ */
+
+const EDIT_PRODUCT_STORE_NAME = exports.EDIT_PRODUCT_STORE_NAME = 'max-marine-edit-product-shared-state';
+const EVENT_PRODUCT_READY = exports.EVENT_PRODUCT_READY = 'max-marine/edit-product/product:ready';
+const EVENT_STOCK_CHANGED = exports.EVENT_STOCK_CHANGED = 'max-marine/edit-product/stock:changed';
+const EVENT_RELISTING_DETECTED = exports.EVENT_RELISTING_DETECTED = 'max-marine/edit-product/relisting:detected';
+const EVENT_RELISTING_CONFIRMED = exports.EVENT_RELISTING_CONFIRMED = 'max-marine/edit-product/relisting:confirmed';
+const EVENT_RELISTING_CANCELLED = exports.EVENT_RELISTING_CANCELLED = 'max-marine/edit-product/relisting:cancelled';
+const EVENT_DUPLICATE_AWAITING_FIRST_SAVE = exports.EVENT_DUPLICATE_AWAITING_FIRST_SAVE = 'max-marine/edit-product/duplicate:awaiting-first-save';
+const EVENT_SAVE_REQUESTED = exports.EVENT_SAVE_REQUESTED = 'max-marine/edit-product/save:requested';
+const EVENT_SAVE_BLOCKED = exports.EVENT_SAVE_BLOCKED = 'max-marine/edit-product/save:blocked';
+const EVENT_SAVE_COMMITTED = exports.EVENT_SAVE_COMMITTED = 'max-marine/edit-product/save:committed';
+const CONTEXT_ALWAYS = exports.CONTEXT_ALWAYS = 'always';
+const CONTEXT_DUPLICATE = exports.CONTEXT_DUPLICATE = 'duplicate';
+const CONTEXT_RELISTING = exports.CONTEXT_RELISTING = 'relisting';
+const SEVERITY_BLOCK = exports.SEVERITY_BLOCK = 'block';
+const SEVERITY_WARN = exports.SEVERITY_WARN = 'warn';

package/dist/edit-product/index.js

@@ -0,0 +1,64 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+var _exportNames = {
+  getRegistry: true,
+  onEditProductEvent: true,
+  registerAction: true,
+  registerField: true,
+  registerRequirement: true,
+  registerOnReady: true
+};
+Object.defineProperty(exports, "getRegistry", {
+  enumerable: true,
+  get: function () {
+    return _registry.getRegistry;
+  }
+});
+Object.defineProperty(exports, "onEditProductEvent", {
+  enumerable: true,
+  get: function () {
+    return _registry.onEditProductEvent;
+  }
+});
+Object.defineProperty(exports, "registerAction", {
+  enumerable: true,
+  get: function () {
+    return _registry.registerAction;
+  }
+});
+Object.defineProperty(exports, "registerField", {
+  enumerable: true,
+  get: function () {
+    return _registry.registerField;
+  }
+});
+Object.defineProperty(exports, "registerOnReady", {
+  enumerable: true,
+  get: function () {
+    return _registerOnReady.default;
+  }
+});
+Object.defineProperty(exports, "registerRequirement", {
+  enumerable: true,
+  get: function () {
+    return _registry.registerRequirement;
+  }
+});
+var _registry = require("./registry");
+var _registerOnReady = _interopRequireDefault(require("./registerOnReady"));
+var _constants = require("./constants");
+Object.keys(_constants).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _constants[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _constants[key];
+    }
+  });
+});
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }

package/dist/edit-product/registerOnReady.js

@@ -0,0 +1,40 @@
+"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 edit product extensions on `domReady`.
+ *
+ * Fields are registered before actions and requirements, because both refer to fields by
+ * key and the registry checks that the key resolves.
+ *
+ * @param  {Object}    registrations               Registration map.
+ * @param  {Object[]}  [registrations.fields]       Field definitions.
+ * @param  {Object[]}  [registrations.actions]      Action definitions.
+ * @param  {Object[]}  [registrations.requirements] Requirement definitions.
+ * @return {void}
+ */
+const registerOnReady = (registrations = {}) => {
+  const {
+    fields = [],
+    actions = [],
+    requirements = []
+  } = registrations;
+  (0, _domReady.default)(() => {
+    fields.forEach(field => {
+      (0, _registry.registerField)(field);
+    });
+    actions.forEach(action => {
+      (0, _registry.registerAction)(action);
+    });
+    requirements.forEach(requirement => {
+      (0, _registry.registerRequirement)(requirement);
+    });
+  });
+};
+var _default = exports.default = registerOnReady;

package/dist/edit-product/registry.js

@@ -0,0 +1,129 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.registerRequirement = exports.registerField = exports.registerAction = exports.onEditProductEvent = exports.getRegistry = void 0;
+/**
+ * Lightweight wrappers around the global edit product registry exposed by
+ * `max-marine-edit-product-shared-state`.
+ *
+ * EPSS owns the registry itself - the field, action and requirement buckets, the
+ * lifecycle events and the save gate. These helpers give consuming plugins a way to
+ * register into it without hand-copying the namespace, in the same shape as the
+ * Data Migrations wrappers alongside them.
+ *
+ * Unlike the Data Migrations registry, this one is created by whichever script reaches
+ * it first. A consumer whose script happens to run before EPSS's still registers
+ * successfully, and EPSS picks up what is already there.
+ */
+
+const NAMESPACE = 'maxMarineEditProduct';
+
+/**
+ * Get the shared registry, creating the slot if nothing has yet.
+ *
+ * Returns null outside a browser, and null if the slot exists but does not look like a
+ * registry - which happens only if something else has claimed the global.
+ *
+ * @return {Object|null}
+ */
+const getRegistry = () => {
+  if ('undefined' === typeof window) {
+    return null;
+  }
+  const registry = window[NAMESPACE];
+  if (!registry || 'function' !== typeof registry.registerField) {
+    return null;
+  }
+  return registry;
+};
+
+/**
+ * Register a field this plugin owns.
+ *
+ * @param  {Object}    field           Field definition.
+ * @param  {string}    field.key       Stable key other plugins refer to this field by.
+ * @param  {string}    field.label     Human label, shown to the employee.
+ * @param  {string}    field.owner     Owning plugin slug.
+ * @param  {string}    [field.group]   Group name used to bucket it in modals.
+ * @param  {Function}  field.read      Returns the current value.
+ * @param  {Function}  field.clear     Empties the field.
+ * @param  {Function}  [field.isEmpty] Whether a value counts as empty.
+ * @param  {Function}  [field.focus]   Moves focus to the field.
+ * @param  {Function}  [field.isDisabled] Whether the field should be skipped entirely.
+ * @return {boolean}
+ */
+exports.getRegistry = getRegistry;
+const registerField = field => {
+  const registry = getRegistry();
+  if (!registry) {
+    return false;
+  }
+  return registry.registerField(field);
+};
+
+/**
+ * Register an action bound to one or more lifecycle contexts.
+ *
+ * @param  {Object}           action           Action definition.
+ * @param  {string}           action.id        Unique action id.
+ * @param  {string|string[]}  action.on        Contexts, e.g. 'relisting' or 'duplicate'.
+ * @param  {string}           [action.label]   Human label, shown to the employee.
+ * @param  {string|string[]}  [action.clears]  Field keys to clear.
+ * @param  {Function}         [action.run]     Extra work beyond clearing fields.
+ * @return {boolean}
+ */
+exports.registerField = registerField;
+const registerAction = action => {
+  const registry = getRegistry();
+  if (!registry) {
+    return false;
+  }
+  return registry.registerAction(action);
+};
+
+/**
+ * Register a requirement that gates saving.
+ *
+ * @param  {Object}    requirement             Requirement definition.
+ * @param  {string}    requirement.id          Unique requirement id.
+ * @param  {string}    [requirement.field]     Field key this requirement is about.
+ * @param  {*}         [requirement.when]      Context name, array, or predicate.
+ * @param  {string}    [requirement.severity]  'block' or 'warn'. Default 'block'.
+ * @param  {string}    [requirement.message]   Message shown to the employee.
+ * @param  {Function}  [requirement.validate]  Custom check, in place of the field's own.
+ * @return {boolean}
+ */
+exports.registerAction = registerAction;
+const registerRequirement = requirement => {
+  const registry = getRegistry();
+  if (!registry) {
+    return false;
+  }
+  return registry.registerRequirement(requirement);
+};
+
+/**
+ * Subscribe to a lifecycle event emitted by the kernel.
+ *
+ * Returns an unsubscribe function, so a caller never has to hold on to the emitter or
+ * remember the matching `off()` call.
+ *
+ * @param  {string}    event     Event name.
+ * @param  {Function}  callback  Handler.
+ * @return {Function}            Call to unsubscribe.
+ */
+exports.registerRequirement = registerRequirement;
+const onEditProductEvent = (event, callback) => {
+  const store = window?.wp?.data?.select?.('max-marine-edit-product-shared-state');
+  const emitter = store && 'function' === typeof store.getEventEmitter ? store.getEventEmitter() : null;
+  if (!emitter) {
+    return () => {};
+  }
+  emitter.on(event, callback);
+  return () => {
+    emitter.off(event, callback);
+  };
+};
+exports.onEditProductEvent = onEditProductEvent;

package/dist/settings/useActiveSection.js

@@ -5,6 +5,16 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var _element = require("@wordpress/element");
+/**
+ * Read the raw section key carried in the URL hash.
+ *
+ * @since  0.6.3
+ * @return {string}  Hash without its leading `#`, or an empty string.
+ */
+const readHash = () => {
+  return window.location.hash.replace(/^#/, '');
+};
+
 /**
  * Read the section key carried in the URL hash.
  *
@@ -13,7 +23,7 @@ var _element = require("@wordpress/element");
  * @return {string|null}  Matching section key, or null when the hash names nothing known.
  */
 const readSectionFromHash = keys => {
-  const hash = window.location.hash.replace(/^#/, '');
+  const hash = readHash();
   return keys.includes(hash) ? hash : null;
 };
 
@@ -26,6 +36,15 @@ const readSectionFromHash = keys => {
  * the browser Back button still leaves the settings page instead of walking back
  * through the sections that were opened.
  *
+ * A page whose sections depend on a setting registers them in two passes: the first
+ * render happens before `/wp/v2/settings` answers, so any section gated behind a
+ * value is missing from `sections` at that point. A hash naming one of those is
+ * therefore unknown when the page mounts. Rather than discard it and fall back to
+ * the first section, the requested key is parked and adopted as soon as it appears,
+ * which is what makes a link to a gated section work. The parked key is dropped the
+ * moment the reader chooses a section themselves, so a late arriving section can
+ * never pull them away from what they are looking at.
+ *
  * @since  0.6.0
  * @param  {Array}  sections  Section definitions.
  * @return {Array}            The active section key and a setter for it.
@@ -35,15 +54,26 @@ const useActiveSection = sections => {
   const keys = (0, _element.useMemo)(() => {
     return keySignature.split('|').filter(Boolean);
   }, [keySignature]);
+  const requestedSection = (0, _element.useRef)(null);
   const [activeKey, setActiveKey] = (0, _element.useState)(() => {
+    const hash = readHash();
+    if (hash && !keys.includes(hash)) {
+      requestedSection.current = hash;
+    }
     return readSectionFromHash(keys) || keys[0] || '';
   });
   (0, _element.useEffect)(() => {
     const handleHashChange = () => {
-      const nextKey = readSectionFromHash(keys);
-      if (nextKey) {
-        setActiveKey(nextKey);
+      const hash = readHash();
+      if (!hash) {
+        return;
       }
+      if (keys.includes(hash)) {
+        requestedSection.current = null;
+        setActiveKey(hash);
+        return;
+      }
+      requestedSection.current = hash;
     };
     window.addEventListener('hashchange', handleHashChange);
     return () => {
@@ -51,11 +81,25 @@ const useActiveSection = sections => {
     };
   }, [keys]);
   (0, _element.useEffect)(() => {
+    if (!requestedSection.current) {
+      return;
+    }
+    if (!keys.includes(requestedSection.current)) {
+      return;
+    }
+    setActiveKey(requestedSection.current);
+    requestedSection.current = null;
+  }, [keys]);
+  (0, _element.useEffect)(() => {
+    if (requestedSection.current) {
+      return;
+    }
     if (keys.length && !keys.includes(activeKey)) {
       setActiveKey(keys[0]);
     }
   }, [keys, activeKey]);
   const selectSection = (0, _element.useCallback)(key => {
+    requestedSection.current = null;
     setActiveKey(key);
     window.history.replaceState(null, '', `#${key}`);
   }, []);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dream-encode/wp-js-plugin-utils",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "description": "Common JS functionality used by custom WP plugins.",
   "keywords": [
     "wordpress",
@@ -27,6 +27,7 @@
     "./settings/styles": "./dist/settings/styles/_settings-page.scss",
     "./settings/styles/rail": "./dist/settings/styles/_settings-rail.scss",
     "./data-migrations": "./dist/data-migrations/index.js",
+    "./edit-product": "./dist/edit-product/index.js",
     "./components": "./dist/components/index.js",
     "./components/notifications-drawer/styles": "./dist/components/NotificationsDrawer/styles/_notifications-drawer.scss",
     "./components/process/styles": "./dist/components/Process/styles/_process.scss",