@es-joy/jsoe 0.29.0 → 0.31.0

package/dist/search/searchUtils.d.ts

@@ -30,11 +30,75 @@ export function buildPathLabel(schemaObject: import("../formats/schema.js").Zode
  * `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}
  */
-export function findOwnControl(root: HTMLElement, selector: string): HTMLElement | undefined;
+export function findOwnControl(root: Element, selector: string): HTMLElement | undefined;
+/**
+ * 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: Element): boolean;
+/**
+ * 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: Element): void;
+/**
+ * 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: Element, key?: string): void;
 /**
  * A "from"/"to" pair of native inputs sharing one `type`, for the OR-range/
  * Is-Not-Range README affordance (number/bigint/buffersource; `date` uses
@@ -48,6 +112,25 @@ export function findOwnControl(root: HTMLElement, selector: string): HTMLElement
  * 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,
@@ -81,22 +164,34 @@ export function readRangeInputsPair(el: HTMLElement, key?: string): {
  * 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 }: {
+export function buildMultiSelect({ name, options, required }: {
     name: string;
     options: (string | [value: string, title: string])[];
+    required?: boolean;
 }): JamilihArray;
 /**
  * Reads back a `buildMultiSelect` into the selected values, `[]` if none.
- * @param {HTMLElement} el
+ * @param {Element} el
  * @returns {string[]}
  */
-export function readMultiSelect(el: HTMLElement): string[];
+export function readMultiSelect(el: Element): string[];
 /**
  * A tri-state "has property" control for one already-chosen property name
  * (README: "Has property &lt;property pull-down&gt;", "avoid listing
@@ -126,35 +221,71 @@ 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 }: {
+export function buildTriStateSelect({ name, key, trueLabel, falseLabel, onChange, required }: {
     name: string;
     key?: string;
     trueLabel: string;
     falseLabel: string;
+    onChange?: (this: HTMLElement) => void;
+    required?: boolean;
 }): JamilihArray;
 /**
  * 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}
  */
-export function readTriStateSelect(el: HTMLElement, key?: string): boolean | undefined;
+export function readTriStateSelect(el: Element, key?: string): boolean | undefined;
 /**
  * A single checkbox - the only search affordance the README grants
  * `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, disabled }: {
     name: string;
     label: string;
+    checked?: boolean;
+    disabled?: boolean;
 }): JamilihArray;
 /**
  * Reads back a `buildCheckbox`.
@@ -174,17 +305,59 @@ export function readCheckbox(el: HTMLElement): boolean;
  * (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 }: {
     name: string;
     key?: string;
+    onModeChange?: (this: HTMLElement) => void;
+    flagOptions?: string[];
 }): JamilihArray;
 /**
  * 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]
@@ -216,10 +389,169 @@ 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}
  */
-export function readLengthSizeQuery(el: HTMLElement, path: string): import("./queryTree.js").QueryLengthSizeLeaf | undefined;
+export function readLengthSizeQuery(el: Element, path: string): import("./queryTree.js").QueryLengthSizeLeaf | undefined;
+/**
+ * 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 }: {
+    name: string;
+    key?: string;
+    label: string;
+    children: JamilihArray[];
+}): JamilihArray[];
+/**
+ * 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: Element, key?: string): boolean;
+/**
+ * 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: Element, key?: string, onToggle?: ((this: HTMLInputElement) => void)): void;
+/**
+ * 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(): JamilihArray;
+/**
+ * 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: Element, isSatisfied: () => boolean): void;
+/**
+ * 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: Element): void;
+/**
+ * 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: Element, required: boolean): void;
 export type JamilihArray = import("../types.js").JamilihArray;
 //# sourceMappingURL=searchUtils.d.ts.map

package/dist/search/searchUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"searchUtils.d.ts","sourceRoot":"","sources":["../../src/search/searchUtils.js"],"names":[],"mappings":"AAGA;;GAEG;AAEH;;;;;;;;;GASG;AACH,6CAJW,OAAO,sBAAsB,EAAE,WAAW,GAAC,SAAS,QACpD,MAAM,GACJ,MAAM,CASlB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qCAJW,WAAW,YACX,MAAM,GACJ,WAAW,GAAC,SAAS,CAMjC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,0EAVW;IACN,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,GAAC,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,GAAC,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,GAAC,MAAM,CAAA;CACrB,GACS,YAAY,EAAE,CAe1B;AAED;;;;;;GAMG;AACH,wCAJW,WAAW,QACX,MAAM,GACJ;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAC,CAUtC;AAED;;;;;;;;;GASG;AACH,oDANW;IACN,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,CAAC,MAAM,GAAC,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,EAAE,CAAA;CACnD,GACS,YAAY,CAOxB;AAED;;;;GAIG;AACH,oCAHW,WAAW,GACT,MAAM,EAAE,CAOpB;AAED;;;;;;;;;;;;;GAaG;AACH,+DAHW;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAC,GAClC,YAAY,CAWxB;AAED;;;;;;;;;;;;;GAaG;AACH,0EAHW;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAC,GACjE,YAAY,CAQxB;AAED;;;;;;GAMG;AACH,uCAJW,WAAW,QACX,MAAM,GACJ,OAAO,GAAC,SAAS,CAU7B;AAED;;;;;;;;GAQG;AACH,+CAHW;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,GAC3B,YAAY,CAOxB;AAED;;;;GAIG;AACH,iCAHW,WAAW,GACT,OAAO,CAMnB;AAED;;;;;;;;;;;;;;GAcG;AACH,yDAHW;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAC,GAC1B,YAAY,CAiBxB;AAED;;;;;;;;;;GAUG;AACH,0CAPW,WAAW,QACX,MAAM,QACN,MAAM,GACJ,OAAO,gBAAgB,EAAE,mBAAmB,GACxD,OAAW,gBAAgB,EAAE,cAAc,GAC3C,OAAW,gBAAgB,EAAE,oBAAoB,GAAC,SAAS,CAuB3D;AAED;;;;;;;;;;;;;GAaG;AACH,2EARW;IACN,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB,GACS,YAAY,EAAE,CAwB1B;AAED;;;;;;GAMG;AACH,wCAJW,WAAW,QACX,MAAM,GACJ,OAAO,gBAAgB,EAAE,mBAAmB,GAAC,SAAS,CAgBlE;2BA9VY,OAAO,aAAa,EAAE,YAAY"}
+{"version":3,"file":"searchUtils.d.ts","sourceRoot":"","sources":["../../src/search/searchUtils.js"],"names":[],"mappings":"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"}

package/dist/search/subTypes/blobHTMLSearchType.d.ts

@@ -1,15 +1,42 @@
 export default blobHTMLSearchType;
 export type SearchTypeObject = import("../searchDispatch.js").SearchTypeObject;
-/**
- * @typedef {import('../searchDispatch.js').SearchTypeObject} SearchTypeObject
- */
 /**
  * Blob HTML: XPath, CSS selectors, full text search, regex search of raw
- * HTML (README) - a mode `<select>` plus one text `<input>`, the same
+ * HTML (README) - a mode `<select>` plus one value control, the same
  * "pick a mode, give it one value" shape as `buildLiteralRegexControls`
  * (`searchUtils.js`), but not built through it: the four modes and the
  * `blobHTML` leaf kind they produce are specific to this one type, with no
- * second caller to share the helper with.
+ * second caller to share the helper with. The value control is a single-line
+ * `<input>` for XPath/CSS-selector/regex, but swaps to a `<textarea>` for
+ * "Full text search" mode alone, since a search phrase in a body of text is
+ * the one mode actually expected to run to more than one line - both share
+ * the same class, so the mode `<select>`'s `change` handler (and `getQuery`)
+ * only need the tag name to tell them apart. Only the currently-visible one
+ * of the pair is ever `required` (toggled alongside `hidden` by the mode
+ * `change` handler): a `required` field that's merely hidden, rather than
+ * also un-required, still blocks the form's validity even though the user
+ * has no way to see or fill it. "CSS selector" is listed ahead of "XPath"
+ * (and is the default mode) as the option most jsoe users will recognize.
+ *
+ * The `change` handler also checks `isExemptedByAncestorHasProperty` before
+ * (re-)asserting `required` on the now-visible control: nested as an
+ * optional object property's own child widget, an enclosing "Has property"
+ * already provides a complete constraint on its own (the same relief
+ * `setDescendantsRequired` gives other `required`-attribute controls), but
+ * that relief is a one-time toggle applied *before* `revalidateDescendants`
+ * re-dispatches a synthetic `change` on this very `<select>` - without this
+ * check, that synthetic event would immediately reassert `required` on
+ * whichever control the current mode makes visible, undoing the exemption
+ * `setDescendantsRequired` had just granted.
+ *
+ * "Regex search of raw HTML" gets its own Flags multi-select (the same
+ * `regexpType.js` `allowedFlags` list `stringSearchType.js`'s literal/regex
+ * control passes as `buildLiteralRegexControls`'s `flagOptions`), shown only
+ * while that mode is chosen, folded into the `blobHTML` leaf's own
+ * `$options` (mirroring `QueryRegexLeaf`'s field of the same name) - and,
+ * via `syncBlobHTMLValueValidity`, included when syntax-checking the Value
+ * itself, since the chosen flags can affect whether a given pattern is
+ * actually valid.
  * @type {SearchTypeObject}
  */
 declare const blobHTMLSearchType: SearchTypeObject;

package/dist/search/subTypes/blobHTMLSearchType.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blobHTMLSearchType.d.ts","sourceRoot":"","sources":["../../../src/search/subTypes/blobHTMLSearchType.js"],"names":[],"mappings":";+BAKa,OAAO,sBAAsB,EAAE,gBAAgB;AAD5D;;GAEG;AAEH;;;;;;;;GAQG;AACH,kCAFU,gBAAgB,CA+CxB"}
+{"version":3,"file":"blobHTMLSearchType.d.ts","sourceRoot":"","sources":["../../../src/search/subTypes/blobHTMLSearchType.js"],"names":[],"mappings":";+BAQa,OAAO,sBAAsB,EAAE,gBAAgB;AA8F5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,kCAFU,gBAAgB,CAoHxB"}

package/dist/search/subTypes/recordSearchType.d.ts

@@ -1,8 +1,5 @@
 export default recordSearchType;
 export type SearchTypeObject = import("../searchDispatch.js").SearchTypeObject;
-/**
- * @typedef {import('../searchDispatch.js').SearchTypeObject} SearchTypeObject
- */
 /**
  * Record search is "key-schema search AND/OR value-schema search,"
  * structurally unlike object's additive "has property" (search plan §1) -
@@ -11,7 +8,10 @@ export type SearchTypeObject = import("../searchDispatch.js").SearchTypeObject;
  * whether a match must come from the *same* entry ("has key 2-4 and value
  * 7-9", README) via the "joint" toggle on the resulting `mapRecordJoint`
  * leaf - also used for `looseRecord`, aliased to this same module in
- * `searchDispatch.js` since the search semantics are identical.
+ * `searchDispatch.js` since the search semantics are identical. Key and
+ * value each get their own `buildOptInFieldset` (see `mapSearchType.js`'s
+ * matching doc for why), but leaving *both* unopted-in is itself invalid via
+ * `buildAtLeastOneSentinel`.
  * @type {SearchTypeObject}
  */
 declare const recordSearchType: SearchTypeObject;

package/dist/search/subTypes/recordSearchType.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"recordSearchType.d.ts","sourceRoot":"","sources":["../../../src/search/subTypes/recordSearchType.js"],"names":[],"mappings":";+BAMa,OAAO,sBAAsB,EAAE,gBAAgB;AAD5D;;GAEG;AAEH;;;;;;;;;;GAUG;AACH,gCAFU,gBAAgB,CA+DxB"}
+{"version":3,"file":"recordSearchType.d.ts","sourceRoot":"","sources":["../../../src/search/subTypes/recordSearchType.js"],"names":[],"mappings":";+BASa,OAAO,sBAAsB,EAAE,gBAAgB;AAa5D;;;;;;;;;;;;;GAaG;AACH,gCAFU,gBAAgB,CAoExB"}

package/dist/search/subTypes/tupleSearchType.d.ts

@@ -1,8 +1,5 @@
 export default tupleSearchType;
 export type SearchTypeObject = import("../searchDispatch.js").SearchTypeObject;
-/**
- * @typedef {import('../searchDispatch.js').SearchTypeObject} SearchTypeObject
- */
 /**
  * Each fixed position gets its own control from `.items[i]`, not one
  * control repeated per element (search plan §1 - unlike the value-editing
@@ -15,6 +12,9 @@ export type SearchTypeObject = import("../searchDispatch.js").SearchTypeObject;
  * items.length`, no sparse toggle - not applicable to a tuple), and the
  * `rest` element itself recurses into its own search widget under the same
  * `*` path-segment convention `arraySearchType.js` uses for its element.
+ * Leaving every position, the rest element, and (when present) the length
+ * unconfigured at once is invalid (`buildAtLeastOneSentinel`), the same as
+ * `arraySearchType.js`/`setSearchType.js`/`filelistSearchType.js`.
  * @type {SearchTypeObject}
  */
 declare const tupleSearchType: SearchTypeObject;

package/dist/search/subTypes/tupleSearchType.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tupleSearchType.d.ts","sourceRoot":"","sources":["../../../src/search/subTypes/tupleSearchType.js"],"names":[],"mappings":";+BAMa,OAAO,sBAAsB,EAAE,gBAAgB;AAD5D;;GAEG;AAEH;;;;;;;;;;;;;GAaG;AACH,+BAFU,gBAAgB,CAuFxB"}
+{"version":3,"file":"tupleSearchType.d.ts","sourceRoot":"","sources":["../../../src/search/subTypes/tupleSearchType.js"],"names":[],"mappings":";+BAUa,OAAO,sBAAsB,EAAE,gBAAgB;AAkB5D;;;;;;;;;;;;;;;;GAgBG;AACH,+BAFU,gBAAgB,CA0GxB"}

package/dist/search/superTypes/buffersourceSearchType.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"buffersourceSearchType.d.ts","sourceRoot":"","sources":["../../../src/search/superTypes/buffersourceSearchType.js"],"names":[],"mappings":";+BAKa,OAAO,sBAAsB,EAAE,gBAAgB;AAD5D;;GAEG;AAEH;;;;;;;;;GASG;AACH,sCAFU,gBAAgB,CA4BxB"}
+{"version":3,"file":"buffersourceSearchType.d.ts","sourceRoot":"","sources":["../../../src/search/superTypes/buffersourceSearchType.js"],"names":[],"mappings":";+BAOa,OAAO,sBAAsB,EAAE,gBAAgB;AAD5D;;GAEG;AAEH;;;;;;;;;GASG;AACH,sCAFU,gBAAgB,CAgCxB"}

package/dist/search/unions/unionFamilySearchType.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"unionFamilySearchType.d.ts","sourceRoot":"","sources":["../../../src/search/unions/unionFamilySearchType.js"],"names":[],"mappings":"AAkBA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,sEAHW;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,OAAO,CAAA;CAAC,GACvC,gBAAgB,CAoH5B;+BAxJY,OAAO,sBAAsB,EAAE,gBAAgB;oCAY/C;IACR,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,OAAO,yBAAyB,EAAE,WAAW,EAAE,CAAA;CACzD"}
+{"version":3,"file":"unionFamilySearchType.d.ts","sourceRoot":"","sources":["../../../src/search/unions/unionFamilySearchType.js"],"names":[],"mappings":"AAkBA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,sEAHW;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,OAAO,CAAA;CAAC,GACvC,gBAAgB,CA4H5B;+BAhKY,OAAO,sBAAsB,EAAE,gBAAgB;oCAY/C;IACR,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,OAAO,yBAAyB,EAAE,WAAW,EAAE,CAAA;CACzD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@es-joy/jsoe",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "type": "module",
   "types": "./dist/index.d.ts",
   "main": "./src/index.js",
@@ -53,7 +53,7 @@
     "style-mod": "^4.1.3",
     "typeson-registry": "14.6.1",
     "w3c-keyname": "^2.2.8",
-    "zod": "^4.6.4",
+    "zod": "^4.6.5",
     "zodexy": "^0.32.0"
   },
   "devDependencies": {
@@ -85,7 +85,7 @@
     "nyc": "^18.0.0",
     "open-cli": "^9.0.0",
     "rimraf": "^6.1.3",
-    "rollup": "4.63.2",
+    "rollup": "4.63.3",
     "rollup-plugin-istanbul": "^5.0.0",
     "rollup-plugin-node-builtins": "^2.1.2",
     "typescript": "^6.0.3",