@es-joy/jsoe 0.28.2 → 0.30.0

package/dist/search/searchUtils.d.ts

@@ -0,0 +1,550 @@
+/**
+ * @typedef {import('../types.js').JamilihArray} JamilihArray
+ */
+/**
+ * Label for a leaf/container's own control, preferring the schema's own
+ * `meta.title`/`meta.description`/`description` (via `schemaLabel`, same
+ * precedence the value-editing side uses) and falling back to the JSON
+ * Pointer path's final segment so every control still has a legible label
+ * even when the schema carries no metadata.
+ * @param {import('../formats/schema.js').ZodexSchema|undefined} schemaObject
+ * @param {string} path
+ * @returns {string}
+ */
+export function buildPathLabel(schemaObject: import("../formats/schema.js").ZodexSchema | undefined, path: string): string;
+/**
+ * Finds a control belonging directly to `root`'s own widget - as opposed to
+ * one belonging to a search widget recursively nested inside it (e.g.
+ * `arraySearchType.js`'s own "size" input vs. a nested array-of-arrays'
+ * element widget's own "size" input, both reachable from `root` via a plain
+ * `querySelectorAll`). A match only counts if the nearest ancestor of the
+ * match carrying `data-search-path` is `root` itself; every search element
+ * carries that attribute (`searchElementUtils.js`'s `findSearchElement`), so
+ * this reliably stops at the first nested search element's boundary.
+ *
+ * This is also why every `build*`/`read*` pair below reads its class-based
+ * selector back through this helper rather than a raw
+ * `root.querySelector(...)`: a fixed class name is safe to reuse across
+ * every instance of a given control on the page precisely because lookups
+ * are always scoped this way, and - unlike a `name` built from a
+ * `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 {Element} root
+ * @param {string} selector
+ * @returns {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
+ * `dateType.js`'s own `buildDateInputControl` instead, since a
+ * `datetime-local` input needs its own ISO-slicing).
+ *
+ * `key` distinguishes multiple range pairs *within one widget* (e.g.
+ * `domrectSearchType.js`'s `x`/`y`/`width`/`height` dimensions, or
+ * `errorSearchType.js`'s `lineNumber`/`columnNumber`): `findOwnControl`
+ * already isolates one widget's controls from another's, but can't tell
+ * 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,
+ *   type?: string,
+ *   min?: string|number,
+ *   max?: string|number,
+ *   step?: string|number
+ * }} cfg
+ * @returns {JamilihArray[]}
+ */
+export function buildRangeInputsPair({ name, key, type, min, max, step }: {
+    name: string;
+    key?: string;
+    type?: string;
+    min?: string | number;
+    max?: string | number;
+    step?: string | number;
+}): JamilihArray[];
+/**
+ * Reads back a `buildRangeInputsPair` - pass the same `key` it was built
+ * with.
+ * @param {HTMLElement} el
+ * @param {string} [key]
+ * @returns {{gte: string, lte: string}}
+ */
+export function readRangeInputsPair(el: HTMLElement, key?: string): {
+    gte: string;
+    lte: 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])[],
+ *   required?: boolean
+ * }} cfg
+ * @returns {JamilihArray}
+ */
+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 {Element} el
+ * @returns {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
+ * required"). `objectSearchType.js` supplies the additive pull-down that
+ * lets a user pick *which* property to add one of these for; this helper is
+ * only the fixed per-property toggle it adds each time, so the "any" state
+ * (no constraint entered) is distinguishable from an explicit "has"/
+ * "doesn't have" - matching `SearchTypeObject.getQuery`'s
+ * `undefined`-means-"no constraint" convention. Shares `readTriStateSelect`
+ * with `buildTriStateSelect` below - same three-value shape, just different
+ * option labels.
+ * @param {{name: string, propertyName: string}} cfg
+ * @returns {JamilihArray}
+ */
+export function buildHasPropertyToggle({ name, propertyName }: {
+    name: string;
+    propertyName: string;
+}): JamilihArray;
+/**
+ * A generic "(any)"/true/false `<select>`, shared by every leaf whose only
+ * constraint is a plain boolean choice - `booleanSearchType.js`'s "true or
+ * false" (README) and `numberSearchType.js`'s "Is/Is Not Integer" both read
+ * back through this same three-way convention rather than each rolling
+ * their own.
+ *
+ * `key` distinguishes multiple tri-states *within one widget* (e.g.
+ * `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.
+ * `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, 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 {Element} el
+ * @param {string} [key]
+ * @returns {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`/`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, checked, disabled }: {
+    name: string;
+    label: string;
+    checked?: boolean;
+    disabled?: boolean;
+}): JamilihArray;
+/**
+ * Reads back a `buildCheckbox`.
+ * @param {HTMLElement} el
+ * @returns {boolean}
+ */
+export function readCheckbox(el: HTMLElement): boolean;
+/**
+ * The mode selector for the README's "string, StringObject, Blob, File,
+ * regexp (source), symbol (description): OR literal or regex search/Does
+ * Not contain search" - one shared control (and reader, below) that
+ * `stringSearchType.js`, `symbolSearchType.js`, and `regexpSearchType.js`
+ * (for its source) each build their own custom element around, since the
+ * query semantics are identical and only the label/target facet differs.
+ *
+ * `key` distinguishes multiple literal/regex controls *within one widget*
+ * (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.
+ *
+ * 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 - `stringSearchType.js` passes `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. Every other caller
+ * (`errorSearchType.js`'s props, `fileSearchType.js`'s name/type,
+ * `domexceptionSearchType.js`'s message) leaves this unset, matching the
+ * README's flags-for-regexp-only-plus-string bullet.
+ * @param {{
+ *   name: string, key?: string, onModeChange?: (this: HTMLElement) => void,
+ *   flagOptions?: string[]
+ * }} cfg
+ * @returns {JamilihArray}
+ */
+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. 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]
+ * @returns {import('./queryTree.js').QueryLiteralSetLeaf|
+ *   import('./queryTree.js').QueryRegexLeaf|
+ *   import('./queryTree.js').QueryNotContainsLeaf|undefined}
+ */
+export function readLiteralRegexQuery(el: HTMLElement, path: string, key?: string): import("./queryTree.js").QueryLiteralSetLeaf | import("./queryTree.js").QueryRegexLeaf | import("./queryTree.js").QueryNotContainsLeaf | undefined;
+/**
+ * Has length/size of &lt;number&gt; (README; array/set/tuple-with-rest/
+ * filelist), + "Is/Is not sparse" for arrays only. Returns `[]` (no
+ * control) when the schema pins an exact length/size, since searching on a
+ * constant is uninteresting - the schema's `min`/`max` otherwise become the
+ * input's HTML `min`/`max` attributes.
+ * @param {{
+ *   name: string,
+ *   min?: number,
+ *   max?: number,
+ *   includeSparse?: boolean
+ * }} cfg
+ * @returns {JamilihArray[]}
+ */
+export function buildLengthSizeControls({ name, min, max, includeSparse }: {
+    name: string;
+    min?: number;
+    max?: number;
+    includeSparse?: boolean;
+}): JamilihArray[];
+/**
+ * Reads back `buildLengthSizeControls` into one `lengthSize` leaf, or
+ * `undefined` if neither the size nor the sparse control was set.
+ * @param {Element} el
+ * @param {string} path
+ * @returns {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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,36 @@
+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 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. 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.
+ *
+ * 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.
+ * @type {SearchTypeObject}
+ */
+declare const blobHTMLSearchType: SearchTypeObject;
+//# sourceMappingURL=blobHTMLSearchType.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"blobHTMLSearchType.d.ts","sourceRoot":"","sources":["../../../src/search/subTypes/blobHTMLSearchType.js"],"names":[],"mappings":";+BAOa,OAAO,sBAAsB,EAAE,gBAAgB;AAD5D;;GAEG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,kCAFU,gBAAgB,CAkFxB"}

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

@@ -0,0 +1,18 @@
+export default recordSearchType;
+export type SearchTypeObject = import("../searchDispatch.js").SearchTypeObject;
+/**
+ * Record search is "key-schema search AND/OR value-schema search,"
+ * structurally unlike object's additive "has property" (search plan §1) -
+ * recurses into both the `key` and `value` schemas' own search widgets
+ * (`*key`/`*value` path segments, `queryTree.js`), and lets the user say
+ * 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. 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;
+//# sourceMappingURL=recordSearchType.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,21 @@
+export default tupleSearchType;
+export type SearchTypeObject = import("../searchDispatch.js").SearchTypeObject;
+/**
+ * Each fixed position gets its own control from `.items[i]`, not one
+ * control repeated per element (search plan §1 - unlike the value-editing
+ * side, this gets a dedicated module rather than delegating to
+ * `arraySearchType.js`, since positions aren't interchangeable). A tuple
+ * with no `rest` has an inherently fixed length (`items.length`), so - as
+ * with a fixed-length array - no length control is shown for it; "with rest
+ * has size search as with arrays" (README) applies once `rest` is present:
+ * total length becomes a variable-length `lengthSize` control (`min:
+ * 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;
+//# sourceMappingURL=tupleSearchType.d.ts.map

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

@@ -0,0 +1 @@
+{"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/SpecialRealNumberSearchType.d.ts

@@ -0,0 +1,14 @@
+export default SpecialRealNumberSearchType;
+export type SearchTypeObject = import("../searchDispatch.js").SearchTypeObject;
+/**
+ * @typedef {import('../searchDispatch.js').SearchTypeObject} SearchTypeObject
+ */
+/**
+ * Special number: multiple select of "Infinity", "-Infinity" (README;
+ * `NaN` is covered separately by `nanSearchType.js`'s presence-only
+ * control, since it's its own zodex schema type - `SpecialRealNumberType.js`
+ * itself covers exactly `Infinity`/`-Infinity`/`-0`, not `NaN`).
+ * @type {SearchTypeObject}
+ */
+declare const SpecialRealNumberSearchType: SearchTypeObject;
+//# sourceMappingURL=SpecialRealNumberSearchType.d.ts.map