@dream-encode/wp-js-plugin-utils 0.4.0 → 0.6.1

package/dist/components/NotificationsDrawer/DismissAllButton.js

@@ -4,9 +4,9 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = void 0;
-var _i18n = require("@wordpress/i18n");
 var _components = require("@wordpress/components");
 var _element = require("@wordpress/element");
+var _i18n = require("@wordpress/i18n");
 var _jsxRuntime = require("react/jsx-runtime");
 /**
  * "Dismiss All" button used inside the notifications drawer.

package/dist/components/Process/ProcessStatusSummary.js

@@ -4,12 +4,12 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = void 0;
-var _i18n = require("@wordpress/i18n");
 var _components = require("@wordpress/components");
 var _element = require("@wordpress/element");
-var _time = require("../../utils/time");
-var _dates = require("../../utils/dates");
+var _i18n = require("@wordpress/i18n");
 var _useValueChangeEffect = _interopRequireDefault(require("../../hooks/useValueChangeEffect"));
+var _dates = require("../../utils/dates");
+var _time = require("../../utils/time");
 var _jsxRuntime = require("react/jsx-runtime");
 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;

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,461 @@
+/*
+ * 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__action {
+		display: flex;
+		align-items: flex-start;
+		gap: 24px;
+		padding: 16px 0;
+		border-bottom: 1px solid #f0f0f1;
+
+		&:first-child {
+			padding-top: 0;
+		}
+
+		&:last-child {
+			padding-bottom: 0;
+			border-bottom: 0;
+		}
+	}
+
+	.de-settings__action-description {
+		flex: 1;
+		min-width: 0;
+
+		strong {
+			display: block;
+			font-size: 13px;
+			color: var( --de-settings-ink );
+		}
+
+		p {
+			margin: 4px 0 0;
+			font-size: 12.5px;
+			line-height: 1.5;
+			color: var( --de-settings-ink-faint );
+			max-width: 78ch;
+		}
+	}
+
+	.de-settings__action-button {
+		flex: none;
+	}
+
+	.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dream-encode/wp-js-plugin-utils",
-  "version": "0.4.0",
+  "version": "0.6.1",
   "description": "Common JS functionality used by custom WP plugins.",
   "keywords": [
     "wordpress",
@@ -25,6 +25,7 @@
     "./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",