Add patron blocking rules help modal with template variables (PP-3866) (#207)

## Description

Adds a patron blocking rules help modal to the SIP2 patron auth service
editor (PP-3866). The modal surfaces template variable names and sample
values fetched live from the ILS, a reference of allowed functions, and
a syntax quick-reference. Several refactors accompany the feature to
keep the codebase clean.

**Features:**
- New `PatronBlockingRulesHelpModal` component with three sections: live
template variables (fetched from the ILS), allowed functions reference
(synced from `circulation/docs/FUNCTIONS.md`), and a Jinja2 syntax
quick-reference
- `?` help button placed directly beside the "Patron Blocking Rules"
label
- Live patron data fields fetched via the existing validation endpoint
and cached with `@tanstack/react-query` via a new `useAvailableFields`
custom hook

**Refactors & fixes:**
- Restored `shiftEntries<T>` helper; `removeRule` was duplicating the
same index-shifting logic inline for `clientErrors` and `serverErrors`
- Replaced manual `useState`/`useEffect` prefetch with `useQuery`;
blur-validation results update the query cache via
`queryClient.setQueryData`
- Added a pending-validation sentinel in `serverErrors` so the Save
button stays blocked while an edited rule expression awaits
re-validation
- Simplified `syncPatronBlockingDocs.js` from ~200 to ~40 lines by
removing a custom Markdown fallback converter and relying directly on
`marked` (added as an explicit devDependency)
- Added a stale-copy warning comment to
`src/content/patronBlockingFunctions.md`
- Added a `Modal.Footer` Close button to `PatronBlockingRulesHelpModal`

**Tests:**
- New `PatronBlockingRulesHelpModal.test.tsx` with 12 isolated unit
tests
- `PatronBlockingRulesEditor.test.tsx` wrapped with
`QueryClientProvider`; significantly expanded test coverage
- `PatronAuthServiceEditForm.test.tsx` wrapped with
`QueryClientProvider` to accommodate `useAvailableFields`
- `patronBlockingRules.test.ts` updated for the new `ValidationResult`
return type; added `availableFields` coverage

## Motivation and Context

PP-3866: Library staff configuring SIP2 patron blocking rules had no
in-app reference for which patron data fields are available or what
syntax is valid. This change adds contextual help that shows live data
pulled from their own ILS, reducing trial-and-error configuration.

## How Has This Been Tested?

- All 227 Jest tests pass (`tests/jest/`)
- TypeScript lint clean (`tslint`)
- Manually verified modal opens/closes, live fields load, and the
functions reference renders correctly

## Checklist:

- [x] I have updated the documentation accordingly.
- [x] All new and existing tests passed.

---------

Co-authored-by: Tim DiLauro <tdilauro@users.noreply.github.com>

Author: dbernstein

README.md

@@ -138,6 +138,48 @@ There are end-to-end tests that run on Nightwatch. This selenium-based test runn
 
 To set up credentials and run the tests, check out the [README](/tests/README.md) in `/tests/.
 
+## Patron Blocking Rules — Keeping Documentation in Sync
+
+The help modal displayed alongside the patron blocking rules editor renders
+documentation sourced from
+[`circulation/docs/FUNCTIONS.md`](../circulation/docs/FUNCTIONS.md).
+Because `circulation-admin` is a separate package, this content is
+pre-processed and committed as a generated TypeScript file:
+
+```
+src/content/patronBlockingFunctionsHtml.ts   ← auto-generated, do not edit by hand
+```
+
+### When to run the sync script
+
+Run the sync script any time `circulation/docs/FUNCTIONS.md` is updated:
+
+```bash
+npm run sync-patron-blocking-docs
+```
+
+The script (`scripts/syncPatronBlockingDocs.js`) reads the markdown from the
+sibling `circulation` repository, converts it to HTML, and overwrites
+`src/content/patronBlockingFunctionsHtml.ts`. Commit the regenerated file
+alongside any other changes.
+
+### Expected repository layout
+
+The script assumes both repositories are checked out as siblings:
+
+```
+/path/to/
+├── circulation/          ← Palace Project Circulation Manager
+│   └── docs/
+│       └── FUNCTIONS.md  ← source of truth for allowed functions
+└── circulation-admin/    ← this repository
+    └── src/content/
+        └── patronBlockingFunctionsHtml.ts  ← generated output
+```
+
+If your layout differs, update the source path at the top of
+`scripts/syncPatronBlockingDocs.js`.
+
 ## Debugging
 
 The [Redux DevTools browser extension](https://github.com/reduxjs/redux-devtools/tree/main/extension) may be used to easily inspect app states and state transitions.

jest.config.js

@@ -4,6 +4,7 @@ module.exports = {
     "\\.(jpg|jpeg|png|gif|eot|otf|webp|svg|ttf|woff|woff2|mp4|webm|wav|mp3|m4a|aac|oga)$":
       "<rootDir>/tests/__mocks__/fileMock.js",
     "\\.(css|less)$": "<rootDir>/tests/__mocks__/styleMock.js",
+    "\\.md$": "<rootDir>/tests/__mocks__/fileMock.js",
   },
   preset: "ts-jest",
   testEnvironment: "jest-fixed-jsdom",

package-lock.json

@@ -32,7 +32,8 @@
     "dev-server": "dotenv -c -- webpack serve --progress --hot --config webpack.dev-server.config",
     "dev-test-axe": "TEST_AXE=true npm run dev",
     "prod": "webpack --progress --config webpack.prod.config",
-    "build-docs": "typedoc --tsconfig tsconfig.json src"
+    "build-docs": "typedoc --tsconfig tsconfig.json src",
+    "sync-patron-blocking-docs": "node scripts/syncPatronBlockingDocs.js"
   },
   "dependencies": {
     "@nypl/dgx-svg-icons": "0.3.4",
@@ -113,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

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/* eslint-disable @typescript-eslint/no-var-requires */
+/**
+ * Reads ../circulation/docs/FUNCTIONS.md, converts it to HTML, and writes
+ * src/content/patronBlockingFunctionsHtml.ts — a TypeScript module that
+ * exports the HTML as a string constant.
+ *
+ * Run via:  npm run sync-patron-blocking-docs
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { marked } = require("marked");
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+const srcMd = path.resolve(__dirname, "../../circulation/docs/FUNCTIONS.md");
+const destTs = path.resolve(
+  __dirname,
+  "../src/content/patronBlockingFunctionsHtml.ts"
+);
+
+if (!fs.existsSync(srcMd)) {
+  console.error(`Source not found: ${srcMd}`);
+  process.exit(1);
+}
+
+const markdown = fs.readFileSync(srcMd, "utf8");
+const html = marked(markdown);
+
+const tsContent = `// AUTO-GENERATED — do not edit by hand.
+// Run \`npm run sync-patron-blocking-docs\` to regenerate from
+// circulation/docs/FUNCTIONS.md.
+const patronBlockingFunctionsHtml = ${JSON.stringify(html)};
+export default patronBlockingFunctionsHtml;
+`;
+
+fs.mkdirSync(path.dirname(destTs), { recursive: true });
+fs.writeFileSync(destTs, tsContent, "utf8");
+console.log(`Written: ${destTs}`);

scripts/syncPatronBlockingDocs.js

@@ -2,21 +2,29 @@ import { PatronBlockingRule } from "../interfaces";
 
 const VALIDATE_URL = "/admin/patron_auth_service_validate_patron_blocking_rule";
 
+export type ValidationResult = {
+  /** Non-null when the server reports a validation error; null on success. */
+  error: string | null;
+  /** The patron data dictionary returned by the SIP call on success; null on error or parse failure. */
+  availableFields: Record<string, unknown> | null;
+};
+
 /**
  * Validate a patron blocking rule expression against live ILS data on the server.
  *
  * The server loads the saved PatronAuthService by serviceId, makes a live
  * authentication call using its configured test credentials, and evaluates
- * the rule expression against the real patron data returned.  Only parse/eval
- * success or failure is reported — the boolean result is discarded.
+ * the rule expression against the real patron data returned.
  *
- * Returns null on success, or an error message string on failure.
+ * On success, returns the available_fields dictionary (patron data from the SIP
+ * call) so callers can display template variable names and sample values to the
+ * user.  On failure, returns the error message string.
  */
 export const validatePatronBlockingRuleExpression = async (
   serviceId: number | undefined,
   rule: PatronBlockingRule,
   csrfToken: string | undefined
-): Promise<string | null> => {
+): Promise<ValidationResult> => {
   const formData = new FormData();
   if (serviceId !== undefined) {
     formData.append("service_id", String(serviceId));
@@ -37,13 +45,28 @@ export const validatePatronBlockingRuleExpression = async (
   });
 
   if (res.ok) {
-    return null;
+    try {
+      const data = await res.json();
+      const fields = data.available_fields;
+      return {
+        error: null,
+        availableFields:
+          fields && typeof fields === "object" && !Array.isArray(fields)
+            ? (fields as Record<string, unknown>)
+            : null,
+      };
+    } catch {
+      return { error: null, availableFields: null };
+    }
   }
 
   try {
     const data = await res.json();
-    return data.detail || "Rule validation failed.";
+    return {
+      error: data.detail || "Rule validation failed.",
+      availableFields: null,
+    };
   } catch {
-    return "Rule validation failed.";
+    return { error: "Rule validation failed.", availableFields: null };
   }
 };