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

package/dist/components/Progress/styles/_progress.scss

@@ -0,0 +1,112 @@
+/*
+ * Generic styling for the wp-plugin-utils Progress component.
+ *
+ * Targets the `<progress>` element rendered by `<Progress>`. Apply to a
+ * selector that matches the `className` prop (defaults to `progress-bar`).
+ *
+ *     .progress-bar {
+ *         @include de-wp-plugin-utils-progress();
+ *     }
+ */
+
+$de-wp-plugin-utils-progress-waiting-color: #f1efef !default;
+$de-wp-plugin-utils-progress-processing-color: #006FE6 !default;
+$de-wp-plugin-utils-progress-complete-color: #65C728 !default;
+$de-wp-plugin-utils-progress-border-radius: 5px !default;
+$de-wp-plugin-utils-progress-shimmer-end-color: rgba(255, 255, 255, 0.3) !default;
+
+@mixin de-wp-plugin-utils-progress(
+	$waiting-color: $de-wp-plugin-utils-progress-waiting-color,
+	$processing-color: $de-wp-plugin-utils-progress-processing-color,
+	$complete-color: $de-wp-plugin-utils-progress-complete-color,
+	$border-radius: $de-wp-plugin-utils-progress-border-radius,
+	$shimmer-end-color: $de-wp-plugin-utils-progress-shimmer-end-color
+) {
+	height: 20px;
+	width: 100%;
+	border-radius: $border-radius;
+	position: relative;
+
+	&::-webkit-progress-bar {
+		background: $waiting-color;
+		border-radius: $border-radius;
+	}
+
+	&.processing {
+		&::after {
+			content: '';
+			position: absolute;
+			top: 0;
+			left: 0;
+			width: 100%;
+			height: 100%;
+			background: linear-gradient(
+				90deg,
+				transparent 0%,
+				$shimmer-end-color 50%,
+				transparent 100%
+			);
+			background-size: 200% 100%;
+			border-radius: $border-radius;
+			animation: de-wp-plugin-utils-progress-shimmer 2s infinite linear;
+			pointer-events: none;
+		}
+
+		&::-webkit-progress-value {
+			background: $processing-color;
+			animation: none;
+		}
+
+		&::-webkit-progress-bar {
+			animation: none;
+		}
+	}
+
+	&.pending,
+	&.queued {
+		&::-webkit-progress-value {
+			background: $waiting-color;
+			animation-name: de-wp-plugin-utils-progress-pulse-waiting;
+			animation-duration: 2s;
+			animation-iteration-count: infinite;
+		}
+
+		&::-webkit-progress-bar {
+			animation-name: de-wp-plugin-utils-progress-pulse-waiting;
+			animation-duration: 2s;
+			animation-iteration-count: infinite;
+		}
+	}
+
+	&.complete {
+		&::-webkit-progress-value {
+			background: $complete-color;
+		}
+	}
+
+	&::-webkit-progress-value,
+	&[value]::-webkit-progress-value {
+		border-radius: $border-radius;
+		transition: all 1s ease;
+	}
+}
+
+@keyframes de-wp-plugin-utils-progress-pulse-waiting {
+	0% {
+		background-color: hsl( 200, 20%, 70% );
+	}
+
+	100% {
+		background-color: hsl( 200, 20%, 95% );
+	}
+}
+
+@keyframes de-wp-plugin-utils-progress-shimmer {
+	0% {
+		background-position: -200% 0;
+	}
+
+	100% {
+		background-position: 200% 0;
+	}
+}

package/dist/components/index.js

@@ -33,7 +33,39 @@ Object.defineProperty(exports, "NotificationsList", {
     return _NotificationsDrawer.NotificationsList;
   }
 });
+Object.defineProperty(exports, "ProcessInfo", {
+  enumerable: true,
+  get: function () {
+    return _Process.default;
+  }
+});
+Object.defineProperty(exports, "ProcessInfoRow", {
+  enumerable: true,
+  get: function () {
+    return _Process.ProcessInfoRow;
+  }
+});
+Object.defineProperty(exports, "ProcessStatusInfo", {
+  enumerable: true,
+  get: function () {
+    return _Process.ProcessStatusInfo;
+  }
+});
+Object.defineProperty(exports, "ProcessStatusSummary", {
+  enumerable: true,
+  get: function () {
+    return _Process.ProcessStatusSummary;
+  }
+});
+Object.defineProperty(exports, "Progress", {
+  enumerable: true,
+  get: function () {
+    return _Progress.default;
+  }
+});
 var _Notices = _interopRequireDefault(require("./Notices"));
 var _NotificationsDrawer = _interopRequireWildcard(require("./NotificationsDrawer"));
+var _Process = _interopRequireWildcard(require("./Process"));
+var _Progress = _interopRequireDefault(require("./Progress"));
 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); }
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }

package/dist/settings/RailSettingsPage.js

@@ -0,0 +1,192 @@
+"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 _SettingsRail = _interopRequireDefault(require("./SettingsRail"));
+var _useActiveSection = _interopRequireDefault(require("./useActiveSection"));
+var _jsxRuntime = require("react/jsx-runtime");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * Settings page shell built around a vertical section rail.
+ *
+ * Sections are declared rather than nested, so the rail, the open pane, the unsaved
+ * markers and the deep link all read from one list. Each entry accepts:
+ *
+ *     key          Unique section key, and the URL hash that opens it.
+ *     title        Rail label and pane heading.
+ *     group        Optional rail group heading. Consecutive sections sharing a group
+ *                  sit under one heading.
+ *     description  Optional sentence under the pane heading.
+ *     badge        Optional count shown against the rail item.
+ *     type         'actions' for a section whose controls run immediately.
+ *     render       Called with the settings object, returns the pane content.
+ *
+ * A page declaring a single section renders without the rail, since a rail holding
+ * one item is chrome rather than navigation. Its status readout moves to the header.
+ *
+ * A section is marked as edited by matching the `section` declared on each field in
+ * `createUseSettings` against the section key, so a field does not have to be listed
+ * twice.
+ *
+ * Everything the page writes goes through the single Save in the header, which names
+ * how many fields it will write. A section of type 'actions' hides Save entirely,
+ * because nothing on such a section is written by it - a button there has already
+ * done its work by the time it returns. Unsaved edits made elsewhere are still
+ * reachable from an actions section through the count, which opens the first section
+ * holding one.
+ *
+ * @since  0.6.0
+ * @param  {Object}    props
+ * @param  {string}    props.title         Page title.
+ * @param  {string}    [props.appVersion]  Optional version shown beside the title.
+ * @param  {Object}    props.settings      Object returned from a `useSettings` hook.
+ * @param  {Array}     props.sections      Section definitions.
+ * @param  {Object}    [props.status]      Optional readout for the rail foot, as `{ tone, text }`.
+ * @param  {Function}  [props.onSave]      Optional override for the save handler.
+ * @param  {string}    [props.textDomain]  Text domain for translated UI strings.
+ * @return {JSX.Element}
+ */const RailSettingsPage = ({
+  title,
+  appVersion,
+  settings,
+  sections = [],
+  status,
+  onSave,
+  textDomain = 'default'
+}) => {
+  const {
+    settingsLoaded,
+    settingsSaving,
+    saveSettings,
+    isDirty = false,
+    dirtyCount = 0,
+    dirtySections = [],
+    discardChanges
+  } = settings;
+  const [activeKey, selectSection] = (0, _useActiveSection.default)(sections);
+  const activeSection = sections.find(section => section.key === activeKey) || sections[0];
+  const isActionsSection = 'actions' === activeSection?.type;
+  const showRail = sections.length > 1;
+  (0, _element.useEffect)(() => {
+    if (!isDirty) {
+      return undefined;
+    }
+    const handleBeforeUnload = event => {
+      event.preventDefault();
+      event.returnValue = '';
+    };
+    window.addEventListener('beforeunload', handleBeforeUnload);
+    return () => {
+      window.removeEventListener('beforeunload', handleBeforeUnload);
+    };
+  }, [isDirty]);
+  const handleSave = async event => {
+    event.preventDefault();
+    if ('function' === typeof onSave) {
+      await onSave(event);
+      return;
+    }
+    await saveSettings();
+  };
+  const unsavedLabel = (0, _i18n.sprintf)(/* translators: %d: number of settings fields holding an unsaved edit. */
+  (0, _i18n._n)('%d unsaved change', '%d unsaved changes', dirtyCount, textDomain), dirtyCount);
+  const saveLabel = () => {
+    if (settingsSaving) {
+      return (0, _i18n.__)('Saving…', textDomain);
+    }
+    if (!isDirty) {
+      return (0, _i18n.__)('Saved', textDomain);
+    }
+    return (0, _i18n.__)('Save', textDomain);
+  };
+  if (!activeSection) {
+    return null;
+  }
+  return /*#__PURE__*/(0, _jsxRuntime.jsxs)("div", {
+    className: "de-settings",
+    children: [/*#__PURE__*/(0, _jsxRuntime.jsxs)("div", {
+      className: "de-settings__header",
+      children: [/*#__PURE__*/(0, _jsxRuntime.jsxs)("div", {
+        className: "de-settings__identity",
+        children: [/*#__PURE__*/(0, _jsxRuntime.jsx)("h1", {
+          className: "de-settings__title",
+          children: title
+        }), !!appVersion && /*#__PURE__*/(0, _jsxRuntime.jsxs)("span", {
+          className: "de-settings__version",
+          children: ["v", appVersion]
+        })]
+      }), !showRail && !!status?.text && /*#__PURE__*/(0, _jsxRuntime.jsxs)("span", {
+        className: `de-settings__status is-${status.tone || 'neutral'}`,
+        children: [/*#__PURE__*/(0, _jsxRuntime.jsx)("span", {
+          className: "de-settings__status-led",
+          "aria-hidden": "true"
+        }), status.text]
+      }), /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
+        className: "de-settings__header-actions",
+        children: isActionsSection ? /*#__PURE__*/(0, _jsxRuntime.jsxs)(_element.Fragment, {
+          children: [/*#__PURE__*/(0, _jsxRuntime.jsx)("span", {
+            className: "de-settings__note",
+            children: (0, _i18n.__)('Actions here run immediately.', textDomain)
+          }), isDirty && dirtySections.length > 0 && /*#__PURE__*/(0, _jsxRuntime.jsx)(_components.Button, {
+            variant: "tertiary",
+            onClick: () => selectSection(dirtySections[0]),
+            children: unsavedLabel
+          })]
+        }) : /*#__PURE__*/(0, _jsxRuntime.jsxs)(_element.Fragment, {
+          children: [isDirty && /*#__PURE__*/(0, _jsxRuntime.jsxs)(_element.Fragment, {
+            children: [/*#__PURE__*/(0, _jsxRuntime.jsx)("span", {
+              className: "de-settings__unsaved",
+              children: unsavedLabel
+            }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_components.Button, {
+              variant: "tertiary",
+              onClick: discardChanges,
+              disabled: settingsSaving,
+              children: (0, _i18n.__)('Discard', textDomain)
+            })]
+          }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_components.Button, {
+            variant: "primary",
+            isBusy: settingsSaving,
+            disabled: !settingsLoaded || settingsSaving || !isDirty,
+            onClick: handleSave,
+            children: saveLabel()
+          })]
+        })
+      })]
+    }), /*#__PURE__*/(0, _jsxRuntime.jsxs)("div", {
+      className: showRail ? 'de-settings__body' : 'de-settings__body is-solo',
+      children: [showRail && /*#__PURE__*/(0, _jsxRuntime.jsx)(_SettingsRail.default, {
+        sections: sections,
+        activeKey: activeSection.key,
+        onSelect: selectSection,
+        dirtySections: dirtySections,
+        status: status,
+        textDomain: textDomain
+      }), /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
+        className: "de-settings__pane",
+        id: `de-settings-pane-${activeSection.key}`,
+        role: "tabpanel",
+        "aria-labelledby": `de-settings-tab-${activeSection.key}`,
+        tabIndex: 0,
+        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, {}), /*#__PURE__*/(0, _jsxRuntime.jsxs)("div", {
+            className: "de-settings__pane-head",
+            children: [/*#__PURE__*/(0, _jsxRuntime.jsx)("h2", {
+              children: activeSection.title
+            }), !!activeSection.description && /*#__PURE__*/(0, _jsxRuntime.jsx)("p", {
+              children: activeSection.description
+            })]
+          }), activeSection.render(settings)]
+        })
+      })]
+    })]
+  });
+};
+var _default = exports.default = RailSettingsPage;

package/dist/settings/SettingsRail.js

@@ -0,0 +1,120 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _element = require("@wordpress/element");
+var _i18n = require("@wordpress/i18n");
+var _jsxRuntime = require("react/jsx-runtime");
+/**
+ * Vertical section navigation for the settings shell.
+ *
+ * Implements the tab pattern: one item is tabbable at a time and the arrow keys move
+ * between them, so the rail costs a single tab stop no matter how many sections a
+ * plugin registers.
+ *
+ * @since  0.6.0
+ * @param  {Object}    props
+ * @param  {Array}     props.sections       Section definitions.
+ * @param  {string}    props.activeKey      Key of the open section.
+ * @param  {Function}  props.onSelect       Called with a section key when one is chosen.
+ * @param  {Array}     [props.dirtySections] Keys of sections holding an unsaved edit.
+ * @param  {Object}    [props.status]       Optional readout for the rail foot, as `{ tone, text }`.
+ * @param  {string}    [props.textDomain]   Text domain for translated UI strings.
+ * @return {JSX.Element}
+ */const SettingsRail = ({
+  sections,
+  activeKey,
+  onSelect,
+  dirtySections = [],
+  status,
+  textDomain = 'default'
+}) => {
+  const itemRefs = (0, _element.useRef)({});
+  const moveFocus = (fromIndex, step) => {
+    const nextIndex = (fromIndex + step + sections.length) % sections.length;
+    const nextKey = sections[nextIndex].key;
+    onSelect(nextKey);
+    itemRefs.current[nextKey]?.focus();
+  };
+  const handleKeyDown = (event, index) => {
+    if ('ArrowDown' === event.key || 'ArrowRight' === event.key) {
+      event.preventDefault();
+      moveFocus(index, 1);
+      return;
+    }
+    if ('ArrowUp' === event.key || 'ArrowLeft' === event.key) {
+      event.preventDefault();
+      moveFocus(index, -1);
+      return;
+    }
+    if ('Home' === event.key) {
+      event.preventDefault();
+      moveFocus(-1, 1);
+      return;
+    }
+    if ('End' === event.key) {
+      event.preventDefault();
+      moveFocus(0, -1);
+    }
+  };
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
+    className: "de-settings__rail",
+    children: /*#__PURE__*/(0, _jsxRuntime.jsxs)("div", {
+      className: "de-settings__rail-inner",
+      children: [/*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
+        className: "de-settings__rail-list",
+        role: "tablist",
+        "aria-orientation": "vertical",
+        "aria-label": (0, _i18n.__)('Settings sections', textDomain),
+        children: sections.map((section, index) => {
+          const previousGroup = index > 0 ? sections[index - 1].group : null;
+          const isActive = section.key === activeKey;
+          const isDirty = dirtySections.includes(section.key);
+          return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_element.Fragment, {
+            children: [!!section.group && section.group !== previousGroup && /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
+              className: "de-settings__rail-group",
+              role: "presentation",
+              children: section.group
+            }), /*#__PURE__*/(0, _jsxRuntime.jsxs)("button", {
+              type: "button",
+              role: "tab",
+              id: `de-settings-tab-${section.key}`,
+              className: "de-settings__rail-item",
+              "aria-selected": isActive,
+              "aria-controls": isActive ? `de-settings-pane-${section.key}` : undefined,
+              tabIndex: isActive ? 0 : -1,
+              ref: element => {
+                itemRefs.current[section.key] = element;
+              },
+              onClick: () => onSelect(section.key),
+              onKeyDown: event => handleKeyDown(event, index),
+              children: [/*#__PURE__*/(0, _jsxRuntime.jsx)("span", {
+                className: "de-settings__rail-title",
+                children: section.title
+              }), undefined !== section.badge && null !== section.badge && /*#__PURE__*/(0, _jsxRuntime.jsx)("span", {
+                className: "de-settings__rail-badge",
+                children: section.badge
+              }), isDirty && /*#__PURE__*/(0, _jsxRuntime.jsx)("span", {
+                className: "de-settings__rail-dirty",
+                role: "img",
+                "aria-label": (0, _i18n.__)('Unsaved changes', textDomain)
+              })]
+            })]
+          }, section.key);
+        })
+      }), !!status?.text && /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
+        className: "de-settings__rail-foot",
+        children: /*#__PURE__*/(0, _jsxRuntime.jsxs)("span", {
+          className: `de-settings__status is-${status.tone || 'neutral'}`,
+          children: [/*#__PURE__*/(0, _jsxRuntime.jsx)("span", {
+            className: "de-settings__status-led",
+            "aria-hidden": "true"
+          }), status.text]
+        })
+      })]
+    })
+  });
+};
+var _default = exports.default = SettingsRail;

package/dist/settings/createUseSettings.js

@@ -10,17 +10,46 @@ 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 }; }
+/**
+ * Serialize a value so two settings payloads can be compared by content.
+ *
+ * Object keys are sorted before serializing. The working values and the values that
+ * came back from the REST endpoint routinely carry the same keys in a different
+ * order - an object rebuilt through a spread is the ordinary case - and a plain
+ * `JSON.stringify` comparison reports that as an edit.
+ *
+ * @since  0.6.0
+ * @param  {*}  value  Value to serialize.
+ * @return {string}    Stable serialization of the value.
+ */
+const stableStringify = value => {
+  if (null === value || undefined === value || 'object' !== typeof value) {
+    return JSON.stringify(value ?? null);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(item => stableStringify(item)).join(',')}]`;
+  }
+  const pairs = Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${stableStringify(value[key])}`);
+  return `{${pairs.join(',')}}`;
+};
+
 /**
  * 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.
+ * defines a field with `key` (option key), optional `defaultValue`,
+ * optional state name overrides, and an optional `section` naming the
+ * settings section the field belongs to.
+ *
+ * The hook keeps the values it loaded, so it can report what has been edited
+ * since. That is what lets a settings page enable Save only when there is
+ * something to write, say how much it will write, mark the sections holding an
+ * edit, and offer a Discard that actually restores something.
  *
  * @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  {Array}    config.fields         Field definitions: `{ key, defaultValue, stateName, setterName, section }`.
  * @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.
@@ -37,6 +66,13 @@ const createUseSettings = config => {
   }
   const toCamel = key => key.replace(/[_-](.)/g, (_m, c) => c.toUpperCase());
   const ucFirst = s => s.charAt(0).toUpperCase() + s.slice(1);
+  const sectionByStateName = {};
+  fields.forEach(field => {
+    if (!field.section) {
+      return;
+    }
+    sectionByStateName[field.stateName || toCamel(field.key)] = field.section;
+  });
   return function useSettings() {
     const {
       createSuccessNotice,
@@ -50,6 +86,8 @@ const createUseSettings = config => {
       initialState[stateName] = field.defaultValue !== undefined ? field.defaultValue : '';
     });
     const [values, setValues] = (0, _element.useState)(initialState);
+    const [baseline, setBaseline] = (0, _element.useState)(null);
+    const baselineTaken = (0, _element.useRef)(false);
     const setField = stateName => value => {
       setValues(prev => ({
         ...prev,
@@ -74,27 +112,67 @@ const createUseSettings = config => {
         updateSettingsLoaded(true);
       });
     }, []);
+    (0, _element.useEffect)(() => {
+      if (!settingsLoaded || baselineTaken.current) {
+        return;
+      }
+      baselineTaken.current = true;
+      setBaseline(values);
+    }, [settingsLoaded, values]);
+    const dirtyFields = (0, _element.useMemo)(() => {
+      if (!baseline) {
+        return [];
+      }
+      return Object.keys(values).filter(key => {
+        return stableStringify(values[key]) !== stableStringify(baseline[key]);
+      });
+    }, [values, baseline]);
+    const dirtySections = (0, _element.useMemo)(() => {
+      const sections = [];
+      dirtyFields.forEach(stateName => {
+        const section = sectionByStateName[stateName];
+        if (section && !sections.includes(section)) {
+          sections.push(section);
+        }
+      });
+      return sections;
+    }, [dirtyFields]);
+    const discardChanges = () => {
+      if (!baseline) {
+        return;
+      }
+      setValues(baseline);
+    };
     const saveSettings = async () => {
       updateSettingsSaving(true);
+      const written = values;
       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) {
+      let saveResult;
+      try {
+        saveResult = await (0, _apiFetch.default)({
+          path,
+          method: 'POST',
+          data: {
+            [optionName]: optionData
+          }
+        });
+      } catch (error) {
         updateSettingsSaving(false);
         createErrorNotice((0, _i18n.sprintf)(/* translators: %s: Error message. */
-        (0, _i18n.__)('Error saving settings: %s.', textDomain), saveResult?.message ?? (0, _i18n.__)('Unknown error', textDomain)));
+        (0, _i18n.__)('Error saving settings: %s.', textDomain), error?.message ?? (0, _i18n.__)('Unknown error', textDomain)));
         return;
       }
       updateSettingsSaving(false);
+      if (!saveResult) {
+        createErrorNotice((0, _i18n.sprintf)(/* translators: %s: Error message. */
+        (0, _i18n.__)('Error saving settings: %s.', textDomain), (0, _i18n.__)('Unknown error', textDomain)));
+        return;
+      }
+      setBaseline(written);
       createSuccessNotice((0, _i18n.__)('Settings saved.', textDomain));
     };
     const exposed = {
@@ -104,7 +182,12 @@ const createUseSettings = config => {
       updateSettingsSaving,
       values,
       setValues,
-      saveSettings
+      saveSettings,
+      isDirty: dirtyFields.length > 0,
+      dirtyCount: dirtyFields.length,
+      dirtyFields,
+      dirtySections,
+      discardChanges
     };
     fields.forEach(field => {
       const stateName = field.stateName || toCamel(field.key);

package/dist/settings/getLogLevelStatus.js

@@ -0,0 +1,33 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _i18n = require("@wordpress/i18n");
+/**
+ * Describe a plugin log level as a status readout for the settings rail.
+ *
+ * Debug is called out in amber because it is the level that costs something to leave
+ * switched on, and a settings page is usually the only place that gets noticed.
+ *
+ * @since  0.6.0
+ * @param  {string}  level         Configured log level.
+ * @param  {string}  [textDomain]  Text domain for translated UI strings.
+ * @return {Object}                Status readout, as `{ tone, text }`.
+ */
+const getLogLevelStatus = (level, textDomain = 'default') => {
+  if (!level || 'off' === level) {
+    return {
+      tone: 'neutral',
+      text: (0, _i18n.__)('Logging off', textDomain)
+    };
+  }
+  const label = level.charAt(0).toUpperCase() + level.slice(1);
+  return {
+    tone: 'debug' === level ? 'warn' : 'ok',
+    text: (0, _i18n.sprintf)(/* translators: %s: configured log level, such as Error or Debug. */
+    (0, _i18n.__)('Logging: %s', textDomain), label)
+  };
+};
+var _default = exports.default = getLogLevelStatus;