Refactor PP-3866 help modal: DRY, useQuery, dedicated tests, simplify sync script

- Restore shiftEntries<T> helper; removeRule was duplicating the same
  index-shifting logic inline for clientErrors and serverErrors
- Replace manual useState/useEffect prefetch with useQuery
  (@tanstack/react-query), extracting logic into a new
  src/hooks/useAvailableFields.ts custom hook; blur-validation results
  update the query cache via queryClient.setQueryData
- Add Modal.Footer Close button to PatronBlockingRulesHelpModal so
  users at the bottom of the modal can dismiss without scrolling back up
- Add dedicated PatronBlockingRulesHelpModal.test.tsx with 12 isolated
  unit tests; update editor tests to wrap with QueryClientProvider
- Simplify syncPatronBlockingDocs.js from 203 to 38 lines by removing
  the custom Markdown fallback converter and requiring marked directly
  (added as an explicit devDependency)
- Add stale-copy warning comment to src/content/patronBlockingFunctions.md

Author: dbernstein

package-lock.json

@@ -114,6 +114,7 @@
     "jsdom": "^20.0.3",
     "json-loader": "^0.5.4",
     "lint-staged": "^10.4.0",
+    "marked": "^17.0.6",
     "mini-css-extract-plugin": "1.6.0",
     "mocha": "^10.2.0",
     "msw": "^2.7.3",

package.json

@@ -6,172 +6,13 @@
  * exports the HTML as a string constant.
  *
  * Run via:  npm run sync-patron-blocking-docs
- *
- * Uses the UMD build of `marked` (bundled with the package) for markdown→HTML
- * conversion so this script has no extra runtime dependencies.
  */
 
 "use strict";
 
 const fs = require("fs");
 const path = require("path");
-
-// ---------------------------------------------------------------------------
-// Locate marked UMD build (CJS-compatible, no extra install needed)
-// ---------------------------------------------------------------------------
-let markedFn;
-try {
-  // marked ≥ v5 ships a UMD build at lib/marked.umd.js
-  const { marked } = require("marked/lib/marked.umd.js");
-  markedFn = marked;
-} catch {
-  try {
-    const { marked } = require("marked");
-    markedFn = marked;
-  } catch {
-    // Fallback: very small inline converter covering the elements used in
-    // FUNCTIONS.md (headings, code blocks, inline code, tables, paragraphs,
-    // horizontal rules, bold, lists).
-    markedFn = null;
-  }
-}
-
-function escapeHtml(str) {
-  return str
-    .replace(/&/g, "&")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;");
-}
-
-function convertMarkdown(md) {
-  if (markedFn) {
-    return markedFn(md);
-  }
-
-  // Minimal inline converter for the specific elements in FUNCTIONS.md.
-  const lines = md.split("\n");
-  const out = [];
-  let i = 0;
-
-  while (i < lines.length) {
-    const line = lines[i];
-
-    // Fenced code block
-    if (line.startsWith("```")) {
-      const lang = line.slice(3).trim();
-      const codeLines = [];
-      i++;
-      while (i < lines.length && !lines[i].startsWith("```")) {
-        codeLines.push(escapeHtml(lines[i]));
-        i++;
-      }
-      out.push(
-        `<pre><code${
-          lang ? ` class="language-${escapeHtml(lang)}"` : ""
-        }>${codeLines.join("\n")}</code></pre>`
-      );
-      i++;
-      continue;
-    }
-
-    // Horizontal rule
-    if (/^---+$/.test(line.trim())) {
-      out.push("<hr>");
-      i++;
-      continue;
-    }
-
-    // Headings
-    const headingMatch = line.match(/^(#{1,6})\s+(.*)/);
-    if (headingMatch) {
-      const level = headingMatch[1].length;
-      out.push(`<h${level}>${inlineMarkdown(headingMatch[2])}</h${level}>`);
-      i++;
-      continue;
-    }
-
-    // Table (detect by pipe characters)
-    if (
-      line.includes("|") &&
-      i + 1 < lines.length &&
-      lines[i + 1].match(/^\|?[\s\-|]+\|?$/)
-    ) {
-      const tableLines = [];
-      while (i < lines.length && lines[i].includes("|")) {
-        tableLines.push(lines[i]);
-        i++;
-      }
-      out.push(renderTable(tableLines));
-      continue;
-    }
-
-    // Blank line
-    if (line.trim() === "") {
-      i++;
-      continue;
-    }
-
-    // List item
-    if (/^[-*]\s/.test(line)) {
-      out.push("<ul>");
-      while (i < lines.length && /^[-*]\s/.test(lines[i])) {
-        out.push(`<li>${inlineMarkdown(lines[i].replace(/^[-*]\s/, ""))}</li>`);
-        i++;
-      }
-      out.push("</ul>");
-      continue;
-    }
-
-    // Paragraph
-    const paraLines = [];
-    while (
-      i < lines.length &&
-      lines[i].trim() !== "" &&
-      !lines[i].startsWith("#") &&
-      !lines[i].startsWith("```") &&
-      !lines[i].startsWith("---") &&
-      !lines[i].includes("|")
-    ) {
-      paraLines.push(lines[i]);
-      i++;
-    }
-    if (paraLines.length > 0) {
-      out.push(`<p>${inlineMarkdown(paraLines.join(" "))}</p>`);
-    }
-  }
-
-  return out.join("\n");
-}
-
-function inlineMarkdown(text) {
-  return text
-    .replace(/`([^`]+)`/g, (_, code) => `<code>${escapeHtml(code)}</code>`)
-    .replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>")
-    .replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
-}
-
-function renderTable(tableLines) {
-  const rows = tableLines.map((l) =>
-    l
-      .split("|")
-      .filter((_, idx, arr) => idx > 0 && idx < arr.length - 1)
-      .map((cell) => cell.trim())
-  );
-  const [header, , ...body] = rows; // second row is the separator
-  const headerHtml = header
-    .map((c) => `<th>${inlineMarkdown(escapeHtml(c))}</th>`)
-    .join("");
-  const bodyHtml = body
-    .map(
-      (row) =>
-        `<tr>${row
-          .map((c) => `<td>${inlineMarkdown(escapeHtml(c))}</td>`)
-          .join("")}</tr>`
-    )
-    .join("\n");
-  return `<table class="table table-condensed table-bordered"><thead><tr>${headerHtml}</tr></thead><tbody>${bodyHtml}</tbody></table>`;
-}
+const { marked } = require("marked");
 
 // ---------------------------------------------------------------------------
 // Main
@@ -188,7 +29,7 @@ if (!fs.existsSync(srcMd)) {
 }
 
 const markdown = fs.readFileSync(srcMd, "utf8");
-const html = convertMarkdown(markdown);
+const html = marked(markdown);
 
 const tsContent = `// AUTO-GENERATED — do not edit by hand.
 // Run \`npm run sync-patron-blocking-docs\` to regenerate from

scripts/syncPatronBlockingDocs.js

@@ -6,6 +6,21 @@ import EditableInput from "./EditableInput";
 import WithRemoveButton from "./WithRemoveButton";
 import { validatePatronBlockingRuleExpression } from "../api/patronBlockingRules";
 import PatronBlockingRulesHelpModal from "./PatronBlockingRulesHelpModal";
+import { useAvailableFields } from "../hooks/useAvailableFields";
+
+/** Shifts a numeric-indexed map after an entry at `removedIndex` is deleted.
+ *  Entries below the removed index are kept as-is; entries above are re-keyed
+ *  to index - 1; the entry at the removed index is dropped. */
+function shiftEntries<T>(
+  map: { [k: number]: T },
+  removedIndex: number
+): { [k: number]: T } {
+  return Object.fromEntries(
+    Object.entries(map)
+      .filter(([k]) => Number(k) !== removedIndex)
+      .map(([k, v]) => [Number(k) > removedIndex ? Number(k) - 1 : Number(k), v])
+  ) as { [k: number]: T };
+}
 
 /** Returns the set of non-empty rule names that appear more than once. */
 function getDuplicateNameSet(rules: RuleEntry[]): Set<string> {
@@ -182,15 +197,10 @@ const PatronBlockingRulesEditor = React.forwardRef<
     );
     const [clientErrors, setClientErrors] = React.useState<ClientErrors>({});
     const [serverErrors, setServerErrors] = React.useState<ServerErrors>({});
-
-    // Help modal state
     const [showHelp, setShowHelp] = React.useState(false);
-    const [availableFields, setAvailableFields] = React.useState<Record<
-      string,
-      unknown
-    > | null>(null);
-    const [fieldsLoading, setFieldsLoading] = React.useState(false);
-    const [fieldsError, setFieldsError] = React.useState<string | null>(null);
+
+    const { availableFields, fieldsLoading, fieldsError, updateFields } =
+      useAvailableFields(serviceId, csrfToken);
 
     // Keep stable refs to the latest callbacks so the useEffects below do not
     // need them as dependencies (avoids extra calls when a class-component parent
@@ -220,53 +230,6 @@ const PatronBlockingRulesEditor = React.forwardRef<
       onServerValidationStateChangeRef.current?.(hasServerError);
     }, [serverErrors]);
 
-    // Eagerly pre-fetch available template fields on mount (and whenever
-    // serviceId changes) by calling the validation endpoint with a trivial
-    // passing rule.  This ensures the template-variable table in the help
-    // modal is populated before the user opens it.
-    React.useEffect(() => {
-      if (serviceId === undefined) {
-        setAvailableFields(null);
-        setFieldsError(
-          "Save the service before template variables can be fetched."
-        );
-        return;
-      }
-
-      let cancelled = false;
-      setFieldsLoading(true);
-      setFieldsError(null);
-
-      const trivialRule: PatronBlockingRule = {
-        name: "__prefetch__",
-        rule: "True",
-      };
-      validatePatronBlockingRuleExpression(serviceId, trivialRule, csrfToken)
-        .then((result) => {
-          if (cancelled) return;
-          if (result.error) {
-            setFieldsError(result.error);
-          } else if (result.availableFields) {
-            setAvailableFields(result.availableFields);
-          } else {
-            setFieldsError(
-              "Available fields could not be retrieved. Check that test credentials are configured."
-            );
-          }
-        })
-        .catch(() => {
-          if (cancelled) return;
-          setFieldsError("Failed to fetch available fields.");
-        })
-        .finally(() => {
-          if (!cancelled) setFieldsLoading(false);
-        });
-
-      return () => {
-        cancelled = true;
-      };
-    }, [serviceId, csrfToken]);
-
     const serverErrorMessage = extractErrorMessage(error);
 
     React.useImperativeHandle(
@@ -309,26 +272,8 @@ const PatronBlockingRulesEditor = React.forwardRef<
 
     const removeRule = (index: number) => {
       setRules((prev) => prev.filter((_, i) => i !== index));
-      setClientErrors((prev) => {
-        const next: ClientErrors = {};
-        Object.entries(prev).forEach(([key, val]) => {
-          const k = Number(key);
-          if (k < index) next[k] = val;
-          else if (k > index) next[k - 1] = val;
-          // k === index is dropped
-        });
-        return next;
-      });
-      setServerErrors((prev) => {
-        const next: ServerErrors = {};
-        Object.entries(prev).forEach(([key, val]) => {
-          const k = Number(key);
-          if (k < index) next[k] = val;
-          else if (k > index) next[k - 1] = val;
-          // k === index is dropped
-        });
-        return next;
-      });
+      setClientErrors((prev) => shiftEntries(prev, index));
+      setServerErrors((prev) => shiftEntries(prev, index));
     };
 
     const updateRule = (
@@ -361,9 +306,9 @@ const PatronBlockingRulesEditor = React.forwardRef<
         csrfToken
       );
       setServerErrors((prev) => ({ ...prev, [index]: result.error }));
-      // Keep the most-recent non-null available fields snapshot.
+      // Keep the query cache up-to-date with the most-recent non-null snapshot.
       if (result.availableFields) {
-        setAvailableFields(result.availableFields);
+        updateFields(result.availableFields);
       }
     };
 

src/components/PatronBlockingRulesEditor.tsx

@@ -1,5 +1,6 @@
 import * as React from "react";
 import { Modal } from "react-bootstrap";
+import { Button } from "library-simplified-reusable-components";
 import patronBlockingFunctionsHtml from "../content/patronBlockingFunctionsHtml";
 
 const SIMPLEEVAL_URL = "https://github.com/danthedeckie/simpleeval";
@@ -111,6 +112,14 @@ export function PatronBlockingRulesHelpModal({
           </p>
         </section>
       </Modal.Body>
+      <Modal.Footer>
+        <Button
+          className="inverted left-align small inline"
+          callback={onHide}
+          content="Close"
+          title="Close help modal"
+        />
+      </Modal.Footer>
     </Modal>
   );
 }

src/components/PatronBlockingRulesHelpModal.tsx

@@ -1,3 +1,7 @@
+<!-- REFERENCE COPY — do not edit here.
+     The source of truth is circulation/docs/FUNCTIONS.md.
+     Run `npm run sync-patron-blocking-docs` after updating that file. -->
+
 # Patron Blocking Rules — Allowed Functions
 
 Patron blocking rule expressions are evaluated by a locked-down