@es-joy/jsoe 0.29.0 → 0.31.0

package/src/search/searchUtils.js

@@ -42,7 +42,7 @@ export function buildPathLabel (schemaObject, path) {
  * `typeNamespace` closed over inside a `$define` mixin, which is installed
  * once on the shared custom-element prototype the first time a tag is
  * defined - nothing here depends on a per-instance closure at all.
- * @param {HTMLElement} root
+ * @param {Element} root
  * @param {string} selector
  * @returns {HTMLElement|undefined}
  */
@@ -52,6 +52,113 @@ export function findOwnControl (root, selector) {
   ).find((el) => el.closest('[data-search-path]') === root);
 }
 
+/**
+ * Whether `el` sits inside an `objectSearchType.js` has-property row whose
+ * own "Has"/"Doesn't have" tri-state is *already* explicitly chosen (not
+ * "(any)") - if so, that existence assertion alone is already a complete
+ * constraint for the row, so a per-field "no absent values" requirement
+ * inside it (a range's own "at least one bound", `buildRangeInputsPair`'s
+ * doc) should be relaxed. `setDescendantsRequired` handles this for plain
+ * `required`-attribute controls, but a range pair's requirement is
+ * re-asserted imperatively on every `input`/`change` via `setCustomValidity`
+ * (`syncRangeValidity`, `dateSearchType.js`'s own equivalent) - clearing it
+ * once wouldn't stick past the next keystroke, so those call this directly,
+ * live, instead.
+ *
+ * Returns `false` (not exempted) when `el` also sits inside a
+ * `buildOptInFieldset` fieldset (`jsoeSearchOptInFieldset--*`), for the same
+ * reason `setDescendantsRequired` skips those controls: a dimension range
+ * nested in `makeDomShapeSearchType`'s per-dimension opt-in gate (say,
+ * DOMRect's "Width") is only reachable at all once its own checkbox is
+ * checked, and checking it is itself the user's explicit request to
+ * constrain *that* facet - an enclosing "Has property" shouldn't then let
+ * its "From"/"To" sit blank and still read as valid, any more than
+ * `fileSearchType.js`'s "Name" facet should once opted into.
+ * @param {Element} el
+ * @returns {boolean}
+ */
+export function isExemptedByAncestorHasProperty (el) {
+  if (el.closest('fieldset[class^="jsoeSearchOptInFieldset--"]')) {
+    return false;
+  }
+  const row = el.closest('jsoe-search-has-property');
+  if (!row) {
+    return false;
+  }
+  const select = /** @type {HTMLSelectElement|undefined} */ (
+    findOwnControl(row, 'select.jsoeSearchTriState--')
+  );
+  return select !== undefined && select.value !== '';
+}
+
+/**
+ * Re-runs every `input`/`change`-driven validator within `root` by
+ * re-dispatching those events on each descendant form control -
+ * `objectSearchType.js`'s `buildHasPropertyRow` calls this when its own
+ * "Has"/"Doesn't have" tri-state changes, since a range pair (or anything
+ * else reactive) nested anywhere inside the child widget needs to
+ * re-evaluate `isExemptedByAncestorHasProperty` against the *new* tri-state
+ * value - nothing else would otherwise prompt it to run again until the
+ * user happens to interact with that specific field themselves.
+ * @param {Element} root
+ * @returns {void}
+ */
+export function revalidateDescendants (root) {
+  [...root.querySelectorAll('input, select, textarea')].forEach((el) => {
+    el.dispatchEvent(new Event('input'));
+    el.dispatchEvent(new Event('change'));
+  });
+}
+
+/**
+ * The `buildRangeInputsPair` cross-validation check, factored out so a
+ * consuming widget's own `$define.connectedCallback` (custom elements,
+ * search plan §8) can also call it - the `input`/`change` events
+ * `buildRangeInputsPair` wires below only fire from the user's *first*
+ * interaction, so a freshly-built pair with both ends still empty would
+ * otherwise stay "valid" by the browser's reckoning (no `setCustomValidity`
+ * call has ever run yet) until then, contradicting the "leaving both blank
+ * is invalid" rule documented below. `connectedCallback` is a native
+ * Custom Elements lifecycle method (invoked once per instance the moment it
+ * connects to the document), so calling this from there closes that gap
+ * without needing any build-time live element reference.
+ *
+ * "Leaving both blank is invalid" is itself relaxed when
+ * `isExemptedByAncestorHasProperty` says so - a range nested as a has-
+ * property row's own child widget (e.g. a `date`/`number` property) needs
+ * the same "'Has property X' is already a complete constraint" relief
+ * `setDescendantsRequired` gives `required`-attribute controls, just
+ * re-checked live on every call rather than toggled once, since this runs
+ * imperatively on every keystroke regardless.
+ * @param {Element} root
+ * @param {string} [key]
+ * @returns {void}
+ */
+export function syncRangeValidity (root, key = '') {
+  const gteEl = /** @type {HTMLInputElement|undefined} */ (
+    findOwnControl(root, `input.jsoeSearchRangeGte--${key}`)
+  );
+  const lteEl = /** @type {HTMLInputElement|undefined} */ (
+    findOwnControl(root, `input.jsoeSearchRangeLte--${key}`)
+  );
+  if (!gteEl || !lteEl) {
+    return;
+  }
+  const bothEmpty = gteEl.value === '' && lteEl.value === '' &&
+    !isExemptedByAncestorHasProperty(gteEl);
+  const outOfOrder = gteEl.value !== '' && lteEl.value !== '' &&
+    Number(lteEl.value) < Number(gteEl.value);
+  const emptyMessage = 'Enter at least one bound (From or To).';
+  gteEl.setCustomValidity(bothEmpty ? emptyMessage : '');
+  let lteMessage = '';
+  if (bothEmpty) {
+    lteMessage = emptyMessage;
+  } else if (outOfOrder) {
+    lteMessage = 'End of range must not be less than the start of the range.';
+  }
+  lteEl.setCustomValidity(lteMessage);
+}
+
 /**
  * A "from"/"to" pair of native inputs sharing one `type`, for the OR-range/
  * Is-Not-Range README affordance (number/bigint/buffersource; `date` uses
@@ -65,6 +172,25 @@ export function findOwnControl (root, selector) {
  * apart two same-class controls belonging to the *same* widget, so those
  * need distinct classes. Leave it at the default `''` for the common case
  * of a widget with only one range pair.
+ *
+ * Cross-validates the pair via the native Constraint Validation API,
+ * surfaced by `jsoe.css`'s `input:invalid` styling and a real `<form>`'s
+ * `reportValidity`/`checkValidity` (`src/search/index.js`): leaving *both*
+ * ends blank is invalid - the same "no absent values" reasoning
+ * `buildLiteralRegexControls`'s Value input documents, an added range row
+ * needs at least one bound to mean anything - and if both ends are filled
+ * with "To" less than "From", that's invalid too. An open-ended range (only
+ * one end filled) stays valid. A row nested under an
+ * `objectSearchType.js` required-property's opt-in `<fieldset disabled>`
+ * (or, for `dateSearchType.js`'s own equivalent pair, its own
+ * "Invalid date" fieldset) is unaffected either way, since a disabled field
+ * is excluded from constraint validation entirely. Every caller must also
+ * call `syncRangeValidity` from its own `connectedCallback` (see that
+ * function's doc) so the initial both-blank state is actually invalid from
+ * the moment the widget exists, not just after the user's first keystroke.
+ * `dateSearchType.js`'s own `datetime-local` pair needs the same two checks
+ * but isn't built through this helper (`buildDateInputControl` handles its
+ * own ISO-slicing), so it wires an equivalent handler itself.
  * @param {{
  *   name: string,
  *   key?: string,
@@ -78,14 +204,34 @@ export function findOwnControl (root, selector) {
 export function buildRangeInputsPair ({
   name, key = '', type = 'number', min, max, step
 }) {
+  /**
+   * `this` is whichever of the pair fired the event - `syncRangeValidity`
+   * looks up both fresh via `findOwnControl` rather than closing over
+   * either, so it stays correct however many `buildRangeInputsPair` pairs
+   * (of possibly-differing `key`s) end up sharing the same widget.
+   * @this {HTMLElement}
+   * @returns {void}
+   */
+  function validateRange () {
+    const root = this.closest('[data-search-path]');
+    if (root) {
+      syncRangeValidity(root, key);
+    }
+  }
   return [
     ['label', [
       'From: ',
-      ['input', {name: `${name}-gte`, class: `jsoeSearchRangeGte--${key}`, type, min, max, step}]
+      ['input', {
+        name: `${name}-gte`, class: `jsoeSearchRangeGte--${key}`, type, min, max, step,
+        $on: {input: validateRange, change: validateRange}
+      }]
     ]],
     ['label', [
       'To: ',
-      ['input', {name: `${name}-lte`, class: `jsoeSearchRangeLte--${key}`, type, min, max, step}]
+      ['input', {
+        name: `${name}-lte`, class: `jsoeSearchRangeLte--${key}`, type, min, max, step,
+        $on: {input: validateRange, change: validateRange}
+      }]
     ]]
   ];
 }
@@ -111,14 +257,27 @@ export function readRangeInputsPair (el, key = '') {
  * A `<select multiple>` populated from a fixed candidate list - used by
  * `enum`/`multiSelect`/`literalSet` leaf controls (README: "multiple
  * select").
+ *
+ * `required`, when set, makes leaving *every* option unselected invalid -
+ * `<select multiple required>` is natively satisfied by one or more
+ * selections, no custom validity code needed. `enumSearchType.js` passes
+ * this (an enum widget has nothing else to constrain, so an empty selection
+ * is never a meaningful "no constraint" state - same "no absent values"
+ * reasoning as `buildLiteralRegexControls`'s Value input); other callers
+ * (`regexpSearchType.js`'s Flags, `SpecialRealNumberSearchType.js`) leave it
+ * at the default `false`, since an empty selection there legitimately means
+ * "no constraint on this facet" alongside a widget that has other facets.
  * @param {{
  *   name: string,
- *   options: (string|[value: string, title: string])[]
+ *   options: (string|[value: string, title: string])[],
+ *   required?: boolean
  * }} cfg
  * @returns {JamilihArray}
  */
-export function buildMultiSelect ({name, options}) {
-  return ['select', {name, multiple: true, class: 'jsoeSearchMultiSelect'}, options.map((opt) => {
+export function buildMultiSelect ({name, options, required = false}) {
+  return ['select', {
+    name, multiple: true, required, class: 'jsoeSearchMultiSelect'
+  }, options.map((opt) => {
     const [value, title] = Array.isArray(opt) ? opt : [opt, opt];
     return ['option', {value}, [title]];
   })];
@@ -126,7 +285,7 @@ export function buildMultiSelect ({name, options}) {
 
 /**
  * Reads back a `buildMultiSelect` into the selected values, `[]` if none.
- * @param {HTMLElement} el
+ * @param {Element} el
  * @returns {string[]}
  */
 export function readMultiSelect (el) {
@@ -172,11 +331,36 @@ export function buildHasPropertyToggle ({name, propertyName}) {
  * `dommatrixSearchType.js`'s "Is/Is not Readonly" and "Is/Is not 3d" side
  * by side); see `buildRangeInputsPair`'s doc for why. Leave it at the
  * default `''` for the common case of a widget with only one tri-state.
- * @param {{name: string, key?: string, trueLabel: string, falseLabel: string}} cfg
+ * `onChange`, when given, wires the select's own `change` event too (in
+ * addition to whatever the caller reads back via `readTriStateSelect` at
+ * `getQuery` time) - `dateSearchType.js`'s "Is valid/invalid date" tri-state
+ * uses it to disable the (otherwise irrelevant) From/To range while
+ * "Invalid date" is selected.
+ *
+ * `required`, when set, makes leaving the select at "(any)" invalid - the
+ * "(any)" option's `value: ''` below is exactly what native `required`
+ * treats as "nothing selected", the same trick `unionFamilySearchType.js`'s
+ * "Has type" select and `buildMultiSelect`'s `required` use.
+ * `booleanSearchType.js` passes this (a boolean widget has nothing else to
+ * constrain, so "(any)" is never a meaningful "no constraint" state - same
+ * "no absent values" reasoning as `buildLiteralRegexControls`'s Value
+ * input); other callers (`numberSearchType.js`'s "Is/Is Not Integer",
+ * `dommatrixSearchType.js`'s readonly/3d) leave it at the default `false`,
+ * since those are one of *several* facets in their own widget, where
+ * "(any)" legitimately means "no constraint on this facet".
+ * @param {{
+ *   name: string, key?: string, trueLabel: string, falseLabel: string,
+ *   onChange?: (this: HTMLElement) => void, required?: boolean
+ * }} cfg
  * @returns {JamilihArray}
  */
-export function buildTriStateSelect ({name, key = '', trueLabel, falseLabel}) {
-  return ['select', {name, class: `jsoeSearchTriState--${key}`}, [
+export function buildTriStateSelect ({
+  name, key = '', trueLabel, falseLabel, onChange, required = false
+}) {
+  return ['select', {
+    name, class: `jsoeSearchTriState--${key}`, required,
+    $on: onChange ? {change: onChange} : undefined
+  }, [
     ['option', {value: ''}, ['(any)']],
     ['option', {value: 'true'}, [trueLabel]],
     ['option', {value: 'false'}, [falseLabel]]
@@ -186,7 +370,7 @@ export function buildTriStateSelect ({name, key = '', trueLabel, falseLabel}) {
 /**
  * Reads back a `buildTriStateSelect`/`buildHasPropertyToggle` - pass the
  * same `key` it was built with. `''` (any) maps to `undefined`.
- * @param {HTMLElement} el
+ * @param {Element} el
  * @param {string} [key]
  * @returns {boolean|undefined}
  */
@@ -205,14 +389,26 @@ export function readTriStateSelect (el, key = '') {
  * `undefined`/`void`/`null`/`NaN` ("Require present"; they have "no
  * variants to allow for distinct search", since existence only becomes a
  * meaningful question once the path is optional or nested in a union), and
- * also used by `recordSearchType.js` for its "require same entry" toggle.
- * @param {{name: string, label: string}} cfg
+ * also used by `recordSearchType.js`/`mapSearchType.js` for their "require
+ * same entry" toggle.
+ *
+ * `checked`, when set, pre-checks the checkbox; `disabled` locks it there,
+ * non-interactive. `makePresenceOnlySearchType` passes both: the checkbox
+ * is that leaf's *only* possible constraint, and its whole schema type has
+ * exactly one value ("no variants to allow for distinct search" above) -
+ * there is no second state worth offering a choice between, so this simply
+ * asserts the one meaningful thing outright rather than making the user
+ * pointlessly check a box that could only ever mean one thing. "require
+ * same entry" leaves both at their `false` defaults (interactive,
+ * unchecked), since that's one optional facet alongside a map/record's own
+ * key/value matches, not the whole widget's sole, single-valued constraint.
+ * @param {{name: string, label: string, checked?: boolean, disabled?: boolean}} cfg
  * @returns {JamilihArray}
  */
-export function buildCheckbox ({name, label}) {
+export function buildCheckbox ({name, label, checked = false, disabled = false}) {
   return ['label', [
     `${label}: `,
-    ['input', {type: 'checkbox', name, class: 'jsoeSearchCheckbox'}]
+    ['input', {type: 'checkbox', name, class: 'jsoeSearchCheckbox', checked, disabled}]
   ]];
 }
 
@@ -239,14 +435,126 @@ export function readCheckbox (el) {
  * (e.g. `errorSearchType.js`'s `message`/`name`/`fileName`/`stack`); see
  * `buildRangeInputsPair`'s doc for why. Leave it at the default `''` for
  * the common case of a widget with only one such control.
- * @param {{name: string, key?: string}} cfg
+ *
+ * The Value input is `required`: unlike an untouched range/checkbox/select
+ * (whose empty/default state unambiguously means "no constraint"), a mode
+ * is always selected here (there is no "(any)" option), so an empty Value
+ * next to it is never a meaningful "no constraint" state - it just means
+ * the row was added and never finished. That leaves the whole form invalid
+ * from the moment such a row exists (`buildSearchChoices`'s `<form>`,
+ * `src/search/index.js`) until either a value is entered or (for an
+ * `objectSearchType.js` has-property row) the row is removed via its own
+ * "Remove" button.
+ *
+ * `onModeChange`, when given, wires the mode select's own `change` event
+ * too (in addition to whatever the caller reads back via
+ * `readLiteralRegexQuery` at `getQuery` time) - `regexpSearchType.js` uses
+ * it to show/hide its Flags multi-select, which only makes sense while
+ * "Matches regex" is the chosen mode.
+ *
+ * `flagOptions`, when given, adds a Flags multi-select (options passed in
+ * by the caller - most callers pass `regexpType.js`'s own `allowedFlags`,
+ * the same list `regexpSearchType.js` uses for the actual regexp's own
+ * flags - kept out of this generic module to avoid it depending on a
+ * specific fundamental type), shown only while "Matches regex" is the
+ * chosen mode, the same `$options` a Mongo-flavored `$regex` accepts
+ * alongside it - a plain literal/substring match has no regex to apply
+ * flags to, so it stays hidden otherwise. `regexpSearchType.js`'s own call
+ * (matching against the regexp's `.source` text, not to be confused with
+ * its separate, bespoke Flags control for the regexp's *actual* flags)
+ * leaves this unset, since a flag there would have no real regex of its own
+ * to apply to.
+ *
+ * While "Matches regex" is chosen, the Value input is also live syntax-
+ * checked (`syncLiteralRegexValidity`, below) against
+ * `new RegExp(value, flags)` - an unparsable pattern (or one only invalid
+ * for the currently-selected flags, e.g. `u`/`v`'s stricter escape rules)
+ * sets a custom validity message rather than silently accepting it.
+ * @param {{
+ *   name: string, key?: string, onModeChange?: (this: HTMLElement) => void,
+ *   flagOptions?: string[]
+ * }} cfg
  * @returns {JamilihArray}
  */
-export function buildLiteralRegexControls ({name, key = ''}) {
+export function buildLiteralRegexControls ({name, key = '', onModeChange, flagOptions}) {
+  /**
+   * Live syntax-checks the Value input against `new RegExp(value, flags)`
+   * whenever the current Mode is "Matches regex" - a literal/does-not-
+   * contain Value is a plain string with no format to violate, so this only
+   * has anything to say once "regex" is chosen, and clears back to valid
+   * the moment it isn't. Flags are folded in (read fresh off the Flags
+   * multi-select, when this call has one) because they can themselves flip
+   * a pattern between valid and invalid - the `u`/`v` flags' stricter escape
+   * rules being the main example - so a Flags `change` needs to re-run this
+   * exactly like a Value `input` or a Mode `change` does.
+   * @param {HTMLElement} el - any one of the Mode/Value/Flags controls
+   * @returns {void}
+   */
+  function syncLiteralRegexValidity (el) {
+    const root = el.closest('[data-search-path]');
+    const modeEl = /** @type {HTMLSelectElement|undefined} */ (
+      root ? findOwnControl(root, `select.jsoeSearchMode--${key}`) : undefined
+    );
+    const valueEl = /** @type {HTMLInputElement|undefined} */ (
+      root ? findOwnControl(root, `input.jsoeSearchValue--${key}`) : undefined
+    );
+    if (!modeEl || !valueEl) {
+      return;
+    }
+    if (modeEl.value !== 'regex' || !valueEl.value) {
+      valueEl.setCustomValidity('');
+      return;
+    }
+    const flagsEl = /** @type {HTMLSelectElement|undefined} */ (
+      root ? findOwnControl(root, `select.jsoeSearchRegexFlags--${key}`) : undefined
+    );
+    const flags = [...(flagsEl?.selectedOptions ?? [])].map((opt) => opt.value).join('');
+    try {
+      // eslint-disable-next-line no-new -- Testing
+      new RegExp(valueEl.value, flags);
+      valueEl.setCustomValidity('');
+    } catch {
+      valueEl.setCustomValidity('Enter a valid regular expression.');
+    }
+  }
+  /**
+   * @this {HTMLElement}
+   * @returns {void}
+   */
+  function handleModeChange () {
+    const flagsLabel = this.closest('[data-search-path]')?.querySelector(
+      `.jsoeSearchRegexFlagsLabel--${key}`
+    );
+    if (flagsLabel) {
+      /** @type {HTMLElement} */ (flagsLabel).hidden =
+        /** @type {HTMLSelectElement} */ (this).value !== 'regex';
+    }
+    syncLiteralRegexValidity(this);
+    onModeChange?.call(this);
+  }
+  /** @type {JamilihArray[]} */
+  const flagsChildren = [];
+  if (flagOptions) {
+    flagsChildren.push(['label', {class: `jsoeSearchRegexFlagsLabel--${key}`, hidden: true}, [
+      'Flags: ',
+      ['select', {
+        name: `${name}-flags`, multiple: true, class: `jsoeSearchRegexFlags--${key}`,
+        $on: {
+          /** @this {HTMLElement} */
+          change () {
+            syncLiteralRegexValidity(this);
+          }
+        }
+      }, flagOptions.map((flag) => ['option', {value: flag}, [flag]])]
+    ]]);
+  }
   return ['span', [
     ['label', [
       'Mode: ',
-      ['select', {name: `${name}-mode`, class: `jsoeSearchMode--${key}`}, [
+      ['select', {
+        name: `${name}-mode`, class: `jsoeSearchMode--${key}`,
+        $on: {change: handleModeChange}
+      }, [
         ['option', {value: 'literal'}, ['One of (comma-separated)']],
         ['option', {value: 'regex'}, ['Matches regex']],
         ['option', {value: 'notContains'}, ['Does not contain']]
@@ -254,15 +562,27 @@ export function buildLiteralRegexControls ({name, key = ''}) {
     ]],
     ['label', [
       'Value: ',
-      ['input', {type: 'text', name: `${name}-value`, class: `jsoeSearchValue--${key}`}]
-    ]]
+      ['input', {
+        type: 'text', name: `${name}-value`, class: `jsoeSearchValue--${key}`,
+        required: true,
+        $on: {
+          /** @this {HTMLElement} */
+          input () {
+            syncLiteralRegexValidity(this);
+          }
+        }
+      }]
+    ]],
+    ...flagsChildren
   ]];
 }
 
 /**
  * Reads back `buildLiteralRegexControls` into the corresponding
  * `literalSet`/`regex`/`notContains` leaf - pass the same `key` it was
- * built with.
+ * built with. A `regex` leaf's `$options` is only ever populated when the
+ * caller built this with `flagOptions` (see that function's doc) and at
+ * least one flag is currently selected.
  * @param {HTMLElement} el
  * @param {string} path
  * @param {string} [key]
@@ -281,7 +601,11 @@ export function readLiteralRegexQuery (el, path, key = '') {
     return undefined;
   }
   if (mode === 'regex') {
-    return {kind: 'regex', path, $regex: value};
+    const flagsSelect = /** @type {HTMLSelectElement|undefined} */ (
+      findOwnControl(el, `select.jsoeSearchRegexFlags--${key}`)
+    );
+    const flags = [...(flagsSelect?.selectedOptions ?? [])].map((opt) => opt.value);
+    return {kind: 'regex', path, $regex: value, ...(flags.length ? {$options: flags.join('')} : {})};
   }
   if (mode === 'notContains') {
     return {kind: 'notContains', path, value};
@@ -316,7 +640,11 @@ export function buildLengthSizeControls ({name, min, max, includeSparse}) {
       'Has length/size of: ',
       ['input', {
         type: 'number', name: `${name}-size`, class: 'jsoeSearchSize',
-        min, max, step: 1
+        // A length/size is never negative, regardless of whether the
+        // schema itself declares a (necessarily non-negative) `min` -
+        // floor at 0 rather than leaving the input unbounded below when it
+        // doesn't.
+        min: min === undefined ? 0 : Math.max(min, 0), max, step: 1
       }]
     ]]);
   }
@@ -334,7 +662,7 @@ export function buildLengthSizeControls ({name, min, max, includeSparse}) {
 /**
  * Reads back `buildLengthSizeControls` into one `lengthSize` leaf, or
  * `undefined` if neither the size nor the sparse control was set.
- * @param {HTMLElement} el
+ * @param {Element} el
  * @param {string} path
  * @returns {import('./queryTree.js').QueryLengthSizeLeaf|undefined}
  */
@@ -353,3 +681,227 @@ export function readLengthSizeQuery (el, path) {
     ...(sparseCheck === undefined ? {} : {sparseCheck})
   };
 }
+
+/**
+ * Wraps arbitrary markup - a recursed child search widget's array, or a
+ * fixed facet's own controls (`buildLiteralRegexControls`'s output, say) -
+ * in an opt-in "Search on this" checkbox around a disabled `<fieldset>`.
+ * For a facet that's one of *several* independent, individually-optional
+ * constraints within a parent widget (array/set/tuple/filelist's element
+ * match(es); map/record's key/value; `fileSearchType.js`'s name/content-
+ * type), this keeps that facet's own `required` controls (if it has any)
+ * from forcing the *whole* form invalid just by the facet existing -
+ * generalizes `objectSearchType.js`'s original required-property row (see
+ * that file's history) into a shared helper once enough call sites needed
+ * the identical checkbox+fieldset shape.
+ *
+ * `key` distinguishes multiple opt-in fieldsets *within one widget* (e.g.
+ * `mapSearchType.js`'s "key" and "value"); see `buildRangeInputsPair`'s doc
+ * for why. Leave it at the default `''` for a widget with only one.
+ *
+ * The checkbox's own `name` attribute is `${name}-optIn`, not the bare
+ * `name` passed in: a caller's `name` is typically shared with (a prefix
+ * of) the wrapped content's own field names (`mapSearchType.js`'s "value"
+ * facet, say, names its checkbox from the same `name` its inner value
+ * widget builds its own `-value`-suffixed `<input>` from), and callers
+ * cannot always predict what suffix a given recursed `SearchTypeObject`
+ * will pick - the fixed `-optIn` suffix here guarantees no collision
+ * regardless, without every caller needing to reason about it.
+ *
+ * Call `wireOptInFieldset` once, right after this is built into real DOM
+ * (e.g. inside a `jml(...)` caller, same as `objectSearchType.js`'s rows
+ * do), to actually connect the checkbox to the fieldset's `disabled` state -
+ * this function only builds the static markup (default unchecked/disabled).
+ * @param {{
+ *   name: string, key?: string, label: string, children: JamilihArray[]
+ * }} cfg
+ * @returns {JamilihArray[]}
+ */
+export function buildOptInFieldset ({name, key = '', label, children}) {
+  return [
+    ['label', {class: 'jsoeSearchOptInLabel'}, [
+      `${label}: `,
+      ['input', {type: 'checkbox', name: `${name}-optIn`, class: `jsoeSearchOptIn--${key}`}]
+    ]],
+    ['fieldset', {disabled: true, class: `jsoeSearchOptInFieldset--${key}`}, children]
+  ];
+}
+
+/**
+ * Reads back a `buildOptInFieldset`'s checkbox - pass the same `key` it was
+ * built with.
+ * @param {Element} root
+ * @param {string} [key]
+ * @returns {boolean}
+ */
+export function readOptInChecked (root, key = '') {
+  return Boolean(/** @type {HTMLInputElement|undefined} */ (
+    findOwnControl(root, `input.jsoeSearchOptIn--${key}`)
+  )?.checked);
+}
+
+/**
+ * Connects a `buildOptInFieldset`'s checkbox to toggle its own fieldset's
+ * `disabled` state - call once, synchronously, right after both are live
+ * DOM nodes (see that function's doc). Pass the same `key` it was built
+ * with.
+ *
+ * `onToggle`, when given, is called after each toggle (with the checkbox as
+ * `this`) - `mapSearchType.js`/`recordSearchType.js`/`fileSearchType.js`
+ * use it to re-run their own `syncAtLeastOneCheck` whenever one of their
+ * (exactly two) opt-in facets changes, since checking/unchecking either one
+ * can change whether "at least one" is satisfied.
+ * @param {Element} root
+ * @param {string} [key]
+ * @param {((this: HTMLInputElement) => void)} [onToggle]
+ * @returns {void}
+ */
+export function wireOptInFieldset (root, key = '', onToggle = undefined) {
+  const checkbox = /** @type {HTMLInputElement|undefined} */ (
+    findOwnControl(root, `input.jsoeSearchOptIn--${key}`)
+  );
+  const fieldset = /** @type {HTMLFieldSetElement|undefined} */ (
+    findOwnControl(root, `fieldset.jsoeSearchOptInFieldset--${key}`)
+  );
+  checkbox?.addEventListener('change', () => {
+    if (fieldset) {
+      fieldset.disabled = !checkbox.checked;
+    }
+    onToggle?.call(checkbox);
+  });
+}
+
+/**
+ * A visually-hidden but still-rendered (and so still constraint-validation-
+ * eligible - see `jsoe.css`'s `.searchAtLeastOneSentinel`, the same
+ * "visually-hidden" pattern used for accessibility, which keeps an element
+ * off-screen without `display: none`/`hidden` triggering the Constraint
+ * Validation API's own "not rendered" exemption) sentinel control, for a
+ * widget with several independent optional facets where leaving *every one*
+ * unconfigured should be invalid even though no single facet is itself
+ * always required (`mapSearchType.js`/`recordSearchType.js`'s key/value,
+ * `fileSearchType.js`'s name/content-type). Pair with `syncAtLeastOneCheck`.
+ * @returns {JamilihArray}
+ */
+export function buildAtLeastOneSentinel () {
+  return ['input', {
+    type: 'text', class: 'searchAtLeastOneSentinel', tabindex: -1,
+    'aria-hidden': 'true'
+  }];
+}
+
+/**
+ * @type {WeakMap<Element, () => void>}
+ */
+const atLeastOneResyncs = new WeakMap();
+
+/**
+ * Sets a `buildAtLeastOneSentinel`'s custom validity from a live check -
+ * call once at `connectedCallback` time for the initial state (a freshly-
+ * built widget has satisfied none of its facets yet) and again whenever a
+ * facet that could change the answer does (an opt-in checkbox toggling, a
+ * recursed child's own `input`/`change`).
+ *
+ * Also relaxed, independently of `isSatisfied`, while
+ * `isExemptedByAncestorHasProperty` says an enclosing
+ * `objectSearchType.js` has-property row's own "Has"/"Doesn't have"
+ * already provides a complete constraint - the same relief
+ * `syncRangeValidity` and `dateSearchType.js`'s own range validator give
+ * their "at least one bound" rule, needed here too since a has-property
+ * row's own child could just as easily be an `array`/`map`/`file`/etc.
+ * whose *own* sole constraint is this same "at least one facet" sentinel
+ * rather than a plain `required` attribute or a range pair.
+ *
+ * Every call re-registers `isSatisfied` (keyed by `root` in a `WeakMap`, so
+ * it never leaks past the element's own lifetime) for `resyncAtLeastOne` to
+ * call later. This exists because not every "at least one" widget's own
+ * answer changes via a plain `input`/`change` event - `objectSearchType.js`
+ * itself is the reason: its sentinel changes when a row is added/removed
+ * (a button click, and a structural DOM change, not a value change on any
+ * control), which `revalidateDescendants`' blanket event-redispatch can
+ * never reach, unlike `array`/`map`/etc.'s own opt-in checkboxes and size
+ * inputs. `objectSearchType.js`'s `buildHasPropertyRow` calls
+ * `resyncAtLeastOne` directly instead, precisely because it can't rely on
+ * redispatched events reaching every possible child type.
+ * @param {Element} root
+ * @param {() => boolean} isSatisfied
+ * @returns {void}
+ */
+export function syncAtLeastOneCheck (root, isSatisfied) {
+  atLeastOneResyncs.set(root, () => syncAtLeastOneCheck(root, isSatisfied));
+  const sentinel = /** @type {HTMLInputElement|undefined} */ (
+    findOwnControl(root, 'input.searchAtLeastOneSentinel')
+  );
+  sentinel?.setCustomValidity(
+    isSatisfied() || isExemptedByAncestorHasProperty(root)
+      ? ''
+      : 'Configure at least one of this widget’s facets.'
+  );
+}
+
+/**
+ * Re-runs every `syncAtLeastOneCheck` registered anywhere within `root`
+ * (itself included) - see that function's doc for why this exists
+ * alongside `revalidateDescendants` rather than relying on it alone.
+ * @param {Element} root
+ * @returns {void}
+ */
+export function resyncAtLeastOne (root) {
+  atLeastOneResyncs.get(root)?.();
+  [...root.querySelectorAll('[data-search-path]')].forEach((el) => {
+    atLeastOneResyncs.get(el)?.();
+  });
+}
+
+/**
+ * Toggles the native `required` attribute on every originally-`required`
+ * control inside `root`, leaving everything else (visibility, `disabled`)
+ * alone - unlike `buildOptInFieldset`'s `<fieldset disabled>`, this keeps
+ * the whole subtree fully interactive, for a case where an ancestor's own
+ * choice already provides a complete constraint on its own, but should
+ * still let the recursed child *optionally* add a further constraint on
+ * top rather than blocking interaction with it entirely.
+ * `objectSearchType.js`'s `buildHasPropertyRow` uses this for its "Has"/
+ * "Doesn't have" tri-state: once existence is explicitly asserted either
+ * way, the child's own required inputs (whatever type it turns out to be)
+ * should stop forcing it to be filled in, while a user who still wants to
+ * combine "Has property X" with "X matches Y" can keep typing into it -
+ * `dateSearchType.js`'s "Valid"/"Invalid date" tri-state needs the
+ * equivalent relaxation for its own (structurally different, so not built
+ * through this helper) range pair.
+ *
+ * Relaxing (`required: false`) marks each control it touches with
+ * `data-jsoe-was-required` before clearing the IDL `required` property -
+ * setting that property to `false` reflects back to *removing* the
+ * `required` content attribute entirely (standard boolean-attribute
+ * reflection), so a later call to restore it can't rely on `[required]`
+ * still matching that element; it looks for the marker instead.
+ *
+ * Skips any control inside a `buildOptInFieldset` fieldset
+ * (`jsoeSearchOptInFieldset--*`): that facet already has its own gate on
+ * whether it applies at all (the checkbox's `disabled` toggle exempts it
+ * from constraint validation while unchecked), so an enclosing "Has
+ * property" shouldn't also strip its `required` - a user who explicitly
+ * opts into e.g. `fileSearchType.js`'s "Name" facet under a "Has property"
+ * ancestor still needs to fill in the Value it requires, or uncheck "Name"
+ * again; only the widget's own `buildAtLeastOneSentinel` (which *is*
+ * exempted, via `isExemptedByAncestorHasProperty`) should be satisfied by
+ * "Has property" alone.
+ * @param {Element} root
+ * @param {boolean} required
+ * @returns {void}
+ */
+export function setDescendantsRequired (root, required) {
+  const selector = required ? '[data-jsoe-was-required]' : '[required]';
+  [...root.querySelectorAll(selector)].forEach((el) => {
+    if (el.closest('fieldset[class^="jsoeSearchOptInFieldset--"]')) {
+      return;
+    }
+    if (!required) {
+      /** @type {HTMLElement} */ (el).dataset.jsoeWasRequired = 'true';
+    }
+    /** @type {HTMLInputElement|HTMLSelectElement|HTMLTextAreaElement} */ (
+      el
+    ).required = required;
+  });
+}