@dream-encode/wp-js-plugin-utils 0.3.0 → 0.6.0

package/dist/settings/index.js

@@ -9,12 +9,40 @@ Object.defineProperty(exports, "AdminSettingsPage", {
     return _AdminSettingsPage.default;
   }
 });
+Object.defineProperty(exports, "RailSettingsPage", {
+  enumerable: true,
+  get: function () {
+    return _RailSettingsPage.default;
+  }
+});
+Object.defineProperty(exports, "SettingsRail", {
+  enumerable: true,
+  get: function () {
+    return _SettingsRail.default;
+  }
+});
 Object.defineProperty(exports, "createUseSettings", {
   enumerable: true,
   get: function () {
     return _createUseSettings.default;
   }
 });
+Object.defineProperty(exports, "getLogLevelStatus", {
+  enumerable: true,
+  get: function () {
+    return _getLogLevelStatus.default;
+  }
+});
+Object.defineProperty(exports, "useActiveSection", {
+  enumerable: true,
+  get: function () {
+    return _useActiveSection.default;
+  }
+});
 var _createUseSettings = _interopRequireDefault(require("./createUseSettings"));
 var _AdminSettingsPage = _interopRequireDefault(require("./AdminSettingsPage"));
+var _RailSettingsPage = _interopRequireDefault(require("./RailSettingsPage"));
+var _SettingsRail = _interopRequireDefault(require("./SettingsRail"));
+var _getLogLevelStatus = _interopRequireDefault(require("./getLogLevelStatus"));
+var _useActiveSection = _interopRequireDefault(require("./useActiveSection"));
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }

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

@@ -0,0 +1,421 @@
+/*
+ * Styling for the RailSettingsPage shell.
+ *
+ * A settings page needs both mixins:
+ *
+ *     @use "@dream-encode/wp-js-plugin-utils/dist/settings/styles/settings-rail" as rail;
+ *
+ *     @include rail.de-wp-plugin-utils-settings-rail-page;
+ *
+ *     #my-plugin-settings {
+ *         @include rail.de-wp-plugin-utils-settings-rail;
+ *     }
+ */
+
+/*
+ * Page level resets, included at the top level rather than inside the mount point.
+ *
+ * The rail runs the full width of the screen, which means clearing the left padding
+ * WordPress puts on the content column for its own admin menu.
+ */
+@mixin de-wp-plugin-utils-settings-rail-page {
+	#wpcontent {
+		padding-left: 0;
+	}
+
+	.auto-fold #wpcontent {
+		padding-left: 0;
+	}
+
+	#wpbody-content {
+		padding-bottom: 0;
+	}
+}
+
+@mixin de-wp-plugin-utils-settings-rail {
+	--de-settings-rail-width: 232px;
+	--de-settings-header-height: 61px;
+	--de-settings-admin-bar: 32px;
+	--de-settings-surface: #ffffff;
+	--de-settings-ground: #f0f0f1;
+	--de-settings-line: #dcdcde;
+	--de-settings-ink: #1d2327;
+	--de-settings-ink-soft: #3c434a;
+	--de-settings-ink-faint: #646970;
+	--de-settings-blue: #2271b1;
+	--de-settings-blue-dark: #0a4b78;
+	--de-settings-blue-wash: #f0f6fc;
+	--de-settings-amber: #bd8600;
+	--de-settings-green: #00733f;
+
+	box-sizing: border-box;
+
+	* {
+		box-sizing: border-box;
+	}
+
+	.de-settings {
+		display: flex;
+		flex-direction: column;
+		min-height: calc( 100vh - var( --de-settings-admin-bar ) );
+		background: var( --de-settings-ground );
+	}
+
+	.de-settings__header {
+		position: sticky;
+		top: var( --de-settings-admin-bar );
+		z-index: 10;
+		display: flex;
+		align-items: center;
+		gap: 16px;
+		min-height: var( --de-settings-header-height );
+		padding: 10px 24px;
+		background: var( --de-settings-surface );
+		border-bottom: 1px solid var( --de-settings-line );
+		box-shadow: 0 1px 2px rgba( 0, 0, 0, 0.04 );
+	}
+
+	.de-settings__identity {
+		display: flex;
+		align-items: baseline;
+		gap: 10px;
+		min-width: 0;
+	}
+
+	.de-settings__title {
+		margin: 0;
+		padding: 0;
+		font-size: 1.3rem;
+		font-weight: 600;
+		line-height: 1.3;
+		color: var( --de-settings-ink );
+	}
+
+	.de-settings__version {
+		font-size: 12px;
+		color: var( --de-settings-ink-faint );
+		font-variant-numeric: tabular-nums;
+	}
+
+	.de-settings__header-actions {
+		display: flex;
+		align-items: center;
+		gap: 10px;
+		margin-left: auto;
+		flex: none;
+	}
+
+	.de-settings__unsaved {
+		display: inline-flex;
+		align-items: center;
+		gap: 7px;
+		font-size: 13px;
+		color: var( --de-settings-amber );
+
+		&::before {
+			content: '';
+			width: 8px;
+			height: 8px;
+			border-radius: 50%;
+			background: var( --de-settings-amber );
+		}
+	}
+
+	.de-settings__note {
+		font-size: 13px;
+		color: var( --de-settings-ink-faint );
+	}
+
+	.de-settings__body {
+		display: grid;
+		grid-template-columns: var( --de-settings-rail-width ) minmax( 0, 1fr );
+		flex: 1;
+	}
+
+	.de-settings__body.is-solo {
+		grid-template-columns: minmax( 0, 1fr );
+	}
+
+	.de-settings__rail {
+		background: var( --de-settings-surface );
+		border-right: 1px solid var( --de-settings-line );
+	}
+
+	.de-settings__rail-inner {
+		position: sticky;
+		top: calc( var( --de-settings-admin-bar ) + var( --de-settings-header-height ) );
+		display: flex;
+		flex-direction: column;
+		max-height: calc( 100vh - var( --de-settings-admin-bar ) - var( --de-settings-header-height ) );
+		padding-top: 8px;
+	}
+
+	.de-settings__rail-list {
+		overflow-y: auto;
+		padding-bottom: 12px;
+	}
+
+	.de-settings__rail-group {
+		padding: 14px 16px 5px;
+		font-size: 11px;
+		font-weight: 600;
+		letter-spacing: 0.08em;
+		text-transform: uppercase;
+		color: #8c8f94;
+	}
+
+	.de-settings__rail-item {
+		display: flex;
+		align-items: center;
+		gap: 8px;
+		width: 100%;
+		padding: 9px 14px 9px 13px;
+		border: 0;
+		border-left: 3px solid transparent;
+		background: none;
+		font-size: 13px;
+		line-height: 1.4;
+		text-align: left;
+		color: var( --de-settings-ink-soft );
+		cursor: pointer;
+
+		&:hover {
+			background: #f6f7f7;
+			color: var( --de-settings-blue );
+		}
+
+		&:focus-visible {
+			outline: 2px solid var( --de-settings-blue );
+			outline-offset: -2px;
+		}
+
+		&[aria-selected='true'] {
+			background: var( --de-settings-blue-wash );
+			border-left-color: var( --de-settings-blue );
+			color: var( --de-settings-blue-dark );
+			font-weight: 600;
+		}
+	}
+
+	.de-settings__rail-title {
+		flex: 1;
+		min-width: 0;
+	}
+
+	.de-settings__rail-badge {
+		flex: none;
+		padding: 1px 7px;
+		border-radius: 9px;
+		background: var( --de-settings-ground );
+		font-size: 11px;
+		font-weight: 400;
+		color: var( --de-settings-ink-faint );
+		font-variant-numeric: tabular-nums;
+	}
+
+	.de-settings__rail-dirty {
+		flex: none;
+		width: 7px;
+		height: 7px;
+		border-radius: 50%;
+		background: var( --de-settings-amber );
+	}
+
+	.de-settings__rail-foot {
+		margin-top: auto;
+		padding: 12px 16px;
+		border-top: 1px solid var( --de-settings-line );
+	}
+
+	.de-settings__status {
+		display: flex;
+		align-items: center;
+		gap: 8px;
+		font-size: 12px;
+		color: var( --de-settings-ink-faint );
+
+		.de-settings__status-led {
+			flex: none;
+			width: 8px;
+			height: 8px;
+			border-radius: 50%;
+			background: #8c8f94;
+		}
+
+		&.is-ok .de-settings__status-led {
+			background: var( --de-settings-green );
+			box-shadow: 0 0 0 3px rgba( 0, 115, 63, 0.14 );
+		}
+
+		&.is-warn .de-settings__status-led {
+			background: var( --de-settings-amber );
+			box-shadow: 0 0 0 3px rgba( 189, 134, 0, 0.16 );
+		}
+	}
+
+	.de-settings__pane {
+		min-width: 0;
+		padding: 24px 28px 48px;
+
+		&:focus {
+			outline: none;
+		}
+	}
+
+	.de-settings__pane-head {
+		margin-bottom: 18px;
+
+		h2 {
+			margin: 0 0 4px;
+			padding: 0;
+			font-size: 1.05rem;
+			font-weight: 600;
+			color: var( --de-settings-ink );
+		}
+
+		p {
+			margin: 0;
+			max-width: 78ch;
+			font-size: 13px;
+			color: var( --de-settings-ink-faint );
+		}
+	}
+
+	.de-settings__card {
+		max-width: 1080px;
+		padding: 20px 22px;
+		background: var( --de-settings-surface );
+		border: 1px solid var( --de-settings-line );
+		border-radius: 4px;
+
+		& + & {
+			margin-top: 16px;
+		}
+	}
+
+	.de-settings__fields {
+		display: grid;
+		gap: 20px;
+	}
+
+	.de-settings__field {
+		max-width: 640px;
+
+		.components-base-control,
+		.components-base-control__field,
+		.components-number-control {
+			width: 100%;
+			margin-bottom: 0;
+
+			.components-flex {
+				width: 100%;
+			}
+		}
+
+		label,
+		.components-base-control__label {
+			font-weight: 600;
+		}
+
+		input[type='email'],
+		input[type='number'],
+		input[type='password'],
+		input[type='search'],
+		input[type='tel'],
+		input[type='text'],
+		input[type='url'],
+		textarea {
+			width: 100%;
+		}
+
+		input:disabled,
+		textarea:disabled {
+			background: #f6f7f7;
+			border-color: #dcdcde;
+			color: #a7aaad;
+		}
+
+		.components-input-control__prefix,
+		.components-input-control__suffix {
+			padding: 0 12px;
+			background: #f0f0f1;
+			margin: 0;
+		}
+	}
+
+	.components-placeholder {
+		background: var( --de-settings-surface );
+		border: 1px solid var( --de-settings-line );
+		box-shadow: none;
+
+		.components-placeholder__fieldset {
+			justify-content: center;
+		}
+	}
+
+	.components-notice-list {
+		z-index: 20;
+	}
+
+	@media screen and ( max-width: 1100px ) {
+		.de-settings__body {
+			grid-template-columns: minmax( 0, 1fr );
+		}
+
+		.de-settings__rail {
+			border-right: 0;
+			border-bottom: 1px solid var( --de-settings-line );
+		}
+
+		.de-settings__rail-inner {
+			position: static;
+			max-height: none;
+			padding-top: 0;
+		}
+
+		.de-settings__rail-list {
+			display: flex;
+			overflow-x: auto;
+			padding-bottom: 0;
+		}
+
+		.de-settings__rail-group {
+			display: none;
+		}
+
+		.de-settings__rail-item {
+			width: auto;
+			white-space: nowrap;
+			border-left: 0;
+			border-bottom: 3px solid transparent;
+
+			&[aria-selected='true'] {
+				border-left-color: transparent;
+				border-bottom-color: var( --de-settings-blue );
+			}
+		}
+
+		.de-settings__rail-foot {
+			margin-top: 0;
+			border-top: 1px solid var( --de-settings-line );
+		}
+
+		.de-settings__pane {
+			padding: 20px 16px 40px;
+		}
+	}
+
+	@media screen and ( max-width: 782px ) {
+		--de-settings-admin-bar: 46px;
+
+		.de-settings__header {
+			flex-wrap: wrap;
+			gap: 8px 12px;
+		}
+
+		.de-settings__header-actions {
+			margin-left: 0;
+			width: 100%;
+		}
+	}
+}

package/dist/settings/useActiveSection.js

@@ -0,0 +1,64 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _element = require("@wordpress/element");
+/**
+ * Read the section key carried in the URL hash.
+ *
+ * @since  0.6.0
+ * @param  {Array}  keys  Known section keys.
+ * @return {string|null}  Matching section key, or null when the hash names nothing known.
+ */
+const readSectionFromHash = keys => {
+  const hash = window.location.hash.replace(/^#/, '');
+  return keys.includes(hash) ? hash : null;
+};
+
+/**
+ * Keep the open settings section in the URL.
+ *
+ * A settings section is worth linking to - in a ticket, in a message, in
+ * documentation - and a page that only ever opens on its first section cannot be
+ * linked to at all. The hash is written with `replaceState` rather than pushed, so
+ * the browser Back button still leaves the settings page instead of walking back
+ * through the sections that were opened.
+ *
+ * @since  0.6.0
+ * @param  {Array}  sections  Section definitions.
+ * @return {Array}            The active section key and a setter for it.
+ */
+const useActiveSection = sections => {
+  const keySignature = sections.map(section => section.key).join('|');
+  const keys = (0, _element.useMemo)(() => {
+    return keySignature.split('|').filter(Boolean);
+  }, [keySignature]);
+  const [activeKey, setActiveKey] = (0, _element.useState)(() => {
+    return readSectionFromHash(keys) || keys[0] || '';
+  });
+  (0, _element.useEffect)(() => {
+    const handleHashChange = () => {
+      const nextKey = readSectionFromHash(keys);
+      if (nextKey) {
+        setActiveKey(nextKey);
+      }
+    };
+    window.addEventListener('hashchange', handleHashChange);
+    return () => {
+      window.removeEventListener('hashchange', handleHashChange);
+    };
+  }, [keys]);
+  (0, _element.useEffect)(() => {
+    if (keys.length && !keys.includes(activeKey)) {
+      setActiveKey(keys[0]);
+    }
+  }, [keys, activeKey]);
+  const selectSection = (0, _element.useCallback)(key => {
+    setActiveKey(key);
+    window.history.replaceState(null, '', `#${key}`);
+  }, []);
+  return [activeKey, selectSection];
+};
+var _default = exports.default = useActiveSection;

package/dist/utils/time.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.secondsToDhmsShortIso = exports.secondsToDhmsShort = exports.secondsToDhms = exports.addSecondsToCurrentTime = void 0;
+exports.secondsToDhmsShortIso = exports.secondsToDhmsShort = exports.secondsToDhms = exports.calculateEstimatedTimeRemainingUsingSMA = exports.calculateEstimatedTimeRemainingUsingEMA = exports.calculateEstimatedTimeRemainingSimple = exports.addSecondsToCurrentTime = void 0;
 var _strings = require("./strings");
 /**
  * Convert seconds to a human readable format.
@@ -80,4 +80,135 @@ const addSecondsToCurrentTime = seconds => {
   rawDate = new Date(rawDate.getTime() + Number(seconds * 1000));
   return rawDate.getTime() / 1000;
 };
-exports.addSecondsToCurrentTime = addSecondsToCurrentTime;
+
+/**
+ * Calculate an estimated time remaining based on elapsed time and percent complete.
+ *
+ * @param  {number}  startTime        Unix timestamp (seconds) when the process started.
+ * @param  {number}  percentComplete  Percent complete (0-100).
+ * @return {number}
+ */
+exports.addSecondsToCurrentTime = addSecondsToCurrentTime;
+const calculateEstimatedTimeRemainingSimple = (startTime, percentComplete) => {
+  if (!startTime || percentComplete <= 0 || percentComplete >= 100) {
+    return 0;
+  }
+  const secondsSinceStartTime = Date.now() / 1000 - Number(startTime);
+  const decimalComplete = percentComplete / 100;
+  const totalSeconds = secondsSinceStartTime / decimalComplete;
+  const remaining = totalSeconds - secondsSinceStartTime;
+  return Math.max(1, remaining);
+};
+
+/**
+ * Calculate an estimated time remaining, using Simple Moving Average (SMA).
+ *
+ * @param  {number[]}  times   Array of previous run times (seconds).
+ * @param  {number}    window  Subset of times to use.
+ * @param  {number}    n       Number of loops.
+ * @return {number[]}
+ */
+exports.calculateEstimatedTimeRemainingSimple = calculateEstimatedTimeRemainingSimple;
+const calculateEstimatedTimeRemainingUsingSMA = (times, window = 2, n = Infinity) => {
+  if (!times || times.length < window) {
+    return [];
+  }
+  let index = window - 1;
+  const length = times.length + 1;
+  const simpleMovingAverages = [];
+  let numberOfSMAsCalculated = 0;
+  while (++index < length && numberOfSMAsCalculated++ < n) {
+    const windowSlice = times.slice(index - window, index);
+    const sum = windowSlice.reduce((prev, curr) => prev + curr, 0);
+    simpleMovingAverages.push(sum / window);
+  }
+  return simpleMovingAverages;
+};
+
+/**
+ * Calculate an estimated time remaining, using Exponential Moving Average (EMA).
+ *
+ * Each run object should expose at least `start_time`. Optional fields
+ * `completed_time`, `last_attempt_time` and `total_time` are used when present.
+ *
+ * @param  {Object[]}  runs           Array of process run records.
+ * @param  {number}    window         Subset of times to use.
+ * @param  {boolean}   useCycleTime   Whether to use full cycle time instead of pure processing time.
+ * @return {{emaValues: number[], avgTime: number}}
+ */
+exports.calculateEstimatedTimeRemainingUsingSMA = calculateEstimatedTimeRemainingUsingSMA;
+const calculateEstimatedTimeRemainingUsingEMA = (runs, window = 2, useCycleTime = true) => {
+  if (!runs || runs.length < window + 1) {
+    return {
+      emaValues: [],
+      avgTime: 0
+    };
+  }
+  const sortedRuns = [...runs].sort((a, b) => Number(a.start_time) - Number(b.start_time));
+  let timesToUse = [];
+  if (useCycleTime) {
+    const runsWithCycleTimes = [];
+    for (let i = 1; i < sortedRuns.length; i++) {
+      const previousRun = sortedRuns[i - 1];
+      const currentRun = sortedRuns[i];
+      const processingTime = currentRun.completed_time ? Number(currentRun.completed_time) - Number(currentRun.start_time) : currentRun.last_attempt_time ? Number(currentRun.last_attempt_time) - Number(currentRun.start_time) : 0;
+      const previousEndTime = previousRun.completed_time ? Number(previousRun.completed_time) : previousRun.last_attempt_time ? Number(previousRun.last_attempt_time) : Number(previousRun.start_time);
+      const currentEndTime = currentRun.completed_time ? Number(currentRun.completed_time) : currentRun.last_attempt_time ? Number(currentRun.last_attempt_time) : Number(currentRun.start_time);
+      const cycleTime = currentEndTime - previousEndTime;
+      if (cycleTime > 0 && processingTime > 0) {
+        runsWithCycleTimes.push({
+          ...currentRun,
+          total_time: processingTime,
+          cycle_time: cycleTime
+        });
+      }
+    }
+    if (runsWithCycleTimes.length < window) {
+      return {
+        emaValues: [],
+        avgTime: 0
+      };
+    }
+    timesToUse = runsWithCycleTimes.map(run => run.cycle_time);
+  } else {
+    timesToUse = sortedRuns.map(run => {
+      if (typeof run.total_time === 'number' && run.total_time > 0) {
+        return run.total_time;
+      }
+      const startTime = run.start_time ? Number(run.start_time) : null;
+      const endTime = run.completed_time ? Number(run.completed_time) : run.last_attempt_time ? Number(run.last_attempt_time) : null;
+      return startTime && endTime ? endTime - startTime : 0;
+    }).filter(time => time > 0);
+    if (timesToUse.length < window) {
+      return {
+        emaValues: [],
+        avgTime: 0
+      };
+    }
+  }
+  let index = window - 1;
+  let previousEmaIndex = 0;
+  const length = timesToUse.length;
+  const smoothingFactor = 2 / (window + 1);
+  const exponentialMovingAverages = [];
+  const smaValues = calculateEstimatedTimeRemainingUsingSMA(timesToUse, window, 1);
+  const sma = smaValues.length > 0 ? smaValues[0] : 0;
+  if (sma <= 0) {
+    return {
+      emaValues: [],
+      avgTime: 0
+    };
+  }
+  exponentialMovingAverages.push(sma);
+  while (++index < length) {
+    const value = timesToUse[index];
+    const previousEma = exponentialMovingAverages[previousEmaIndex++];
+    const currentEma = (value - previousEma) * smoothingFactor + previousEma;
+    exponentialMovingAverages.push(currentEma);
+  }
+  return {
+    emaValues: exponentialMovingAverages,
+    avgTime: exponentialMovingAverages.length > 0 ? exponentialMovingAverages[exponentialMovingAverages.length - 1] : 0
+  };
+};
+exports.calculateEstimatedTimeRemainingUsingEMA = calculateEstimatedTimeRemainingUsingEMA;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dream-encode/wp-js-plugin-utils",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "description": "Common JS functionality used by custom WP plugins.",
   "keywords": [
     "wordpress",
@@ -25,9 +25,12 @@
     "./postcss": "./dist/webpack/postcss.config.js",
     "./settings": "./dist/settings/index.js",
     "./settings/styles": "./dist/settings/styles/_settings-page.scss",
+    "./settings/styles/rail": "./dist/settings/styles/_settings-rail.scss",
     "./data-migrations": "./dist/data-migrations/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",
+    "./components/progress/styles": "./dist/components/Progress/styles/_progress.scss",
     "./hooks": "./dist/hooks/index.js",
     "./api": "./dist/api/index.js",
     "./utils": "./dist/utils/index.js",