@es-joy/jsoe 0.28.2 → 0.29.0

package/src/search/fundamentalTypes/mapSearchType.js

@@ -0,0 +1,87 @@
+import {buildPathLabel, buildCheckbox, readCheckbox, buildLengthSizeControls, readLengthSizeQuery} from '../searchUtils.js';
+import {makeMapRecordJointLeaf, combineAnd} from '../queryTreeBuilders.js';
+import {findSearchElement, getQueryViaElement, hasGetQuery} from '../searchElementUtils.js';
+import {buildSearchWidget} from '../searchDispatch.js';
+
+/**
+ * @typedef {import('../searchDispatch.js').SearchTypeObject} SearchTypeObject
+ */
+
+/**
+ * Map, Record: string-type searches of keys, values; ideally would allow
+ * search to insist on match of key and value (README) - structurally the
+ * same as `recordSearchType.js` (`key`/`value` recursion at `*key`/`*value`
+ * segments, a "require same entry" toggle producing one `mapRecordJoint`
+ * leaf), plus a `lengthSize` control for `min`/`max` (a `Map`, unlike a
+ * `Record`, carries its own size bounds in the schema - the same
+ * affordance `setSearchType.js` gets for the analogous reason), combined
+ * with the joint leaf via `$and`.
+ * @type {SearchTypeObject}
+ */
+const mapSearchType = {
+  buildUI ({schemaObject, path, typeNamespace, topRoot, types, originalJSON}) {
+    const label = buildPathLabel(schemaObject, path);
+    const name = `${typeNamespace}-map`;
+    const mapSchemaObject = /** @type {import('zodexy').SzMap<any, any>} */ (
+      schemaObject
+    );
+    const keyPath = `${path}/*key`;
+    const valuePath = `${path}/*value`;
+    const keyArr = buildSearchWidget({
+      schemaObject: mapSchemaObject.key,
+      path: keyPath,
+      typeNamespace,
+      topRoot,
+      types,
+      originalJSON
+    });
+    const valueArr = buildSearchWidget({
+      schemaObject: mapSchemaObject.value,
+      path: valuePath,
+      typeNamespace,
+      topRoot,
+      types,
+      originalJSON
+    });
+    return ['jsoe-search-map', {
+      dataset: {searchPath: path, searchKind: 'map'},
+      title: label,
+      $define: {
+        /** @this {HTMLElement} */
+        getQuery () {
+          const searchPath = this.dataset.searchPath ?? '';
+          const lengthLeaf = readLengthSizeQuery(this, searchPath);
+          const keyEl = findSearchElement(this, `${searchPath}/*key`);
+          const valueEl = findSearchElement(this, `${searchPath}/*value`);
+          const keyQuery = keyEl && hasGetQuery(keyEl)
+            ? keyEl.getQuery()
+            : undefined;
+          const valueQuery = valueEl && hasGetQuery(valueEl)
+            ? valueEl.getQuery()
+            : undefined;
+          const jointLeaf = keyQuery || valueQuery
+            ? makeMapRecordJointLeaf(searchPath, readCheckbox(this), keyQuery, valueQuery)
+            : undefined;
+          return combineAnd([lengthLeaf, jointLeaf]);
+        }
+      }
+    }, [
+      ['span', {class: 'searchLabel'}, [label]],
+      ...buildLengthSizeControls({
+        name, min: mapSchemaObject.min, max: mapSchemaObject.max, includeSparse: false
+      }),
+      ['div', {class: 'searchMapKey'}, [
+        ['span', ['Key matches: ']],
+        keyArr
+      ]],
+      ['div', {class: 'searchMapValue'}, [
+        ['span', ['Value matches: ']],
+        valueArr
+      ]],
+      buildCheckbox({name: `${name}-joint`, label: 'Require same entry'})
+    ]];
+  },
+  getQuery: getQueryViaElement
+};
+
+export default mapSearchType;

package/src/search/fundamentalTypes/nanSearchType.js

@@ -0,0 +1,11 @@
+import {makePresenceOnlySearchType} from '../searchElementUtils.js';
+
+/**
+ * `NaN`: "no variants to allow for distinct search" (README).
+ * @type {import('../searchDispatch.js').SearchTypeObject}
+ */
+const nanSearchType = makePresenceOnlySearchType({
+  tagName: 'jsoe-search-nan'
+});
+
+export default nanSearchType;

package/src/search/fundamentalTypes/nullSearchType.js

@@ -0,0 +1,11 @@
+import {makePresenceOnlySearchType} from '../searchElementUtils.js';
+
+/**
+ * `null`: "no variants to allow for distinct search" (README).
+ * @type {import('../searchDispatch.js').SearchTypeObject}
+ */
+const nullSearchType = makePresenceOnlySearchType({
+  tagName: 'jsoe-search-null'
+});
+
+export default nullSearchType;

package/src/search/fundamentalTypes/numberSearchType.js

@@ -0,0 +1,52 @@
+import {buildPathLabel, buildRangeInputsPair, readRangeInputsPair, buildTriStateSelect, readTriStateSelect} from '../searchUtils.js';
+import {makeRangeLeaf, makeIntegerCheckLeaf, combineAnd} from '../queryTreeBuilders.js';
+import {getQueryViaElement} from '../searchElementUtils.js';
+
+/**
+ * @typedef {import('../searchDispatch.js').SearchTypeObject} SearchTypeObject
+ */
+
+/**
+ * OR Ranges/Is Not Range, Is/Is Not Integer (README).
+ * @type {SearchTypeObject}
+ */
+const numberSearchType = {
+  buildUI ({schemaObject, path, typeNamespace}) {
+    const label = buildPathLabel(schemaObject, path);
+    const name = `${typeNamespace}-number`;
+    return ['jsoe-search-number', {
+      dataset: {searchPath: path, searchKind: 'number'},
+      title: label,
+      $define: {
+        /** @this {HTMLElement} */
+        getQuery () {
+          const searchPath = this.dataset.searchPath ?? '';
+          const {gte, lte} = readRangeInputsPair(this);
+          const rangeLeaf = gte === '' && lte === ''
+            ? undefined
+            : makeRangeLeaf(searchPath, 'number', {
+              ...(gte === '' ? {} : {$gte: Number(gte)}),
+              ...(lte === '' ? {} : {$lte: Number(lte)})
+            });
+          const isInteger = readTriStateSelect(this);
+          const integerLeaf = isInteger === undefined
+            ? undefined
+            : makeIntegerCheckLeaf(searchPath, isInteger);
+          return combineAnd([rangeLeaf, integerLeaf]);
+        }
+      }
+    }, [
+      ['span', {class: 'searchLabel'}, [label]],
+      ...buildRangeInputsPair({name}),
+      ['label', [
+        'Integer: ',
+        buildTriStateSelect({
+          name: `${name}-integer`, trueLabel: 'Integer', falseLabel: 'Not integer'
+        })
+      ]]
+    ]];
+  },
+  getQuery: getQueryViaElement
+};
+
+export default numberSearchType;

package/src/search/fundamentalTypes/objectSearchType.js

@@ -0,0 +1,148 @@
+import {jml} from '../../vendor-imports.js';
+import {escapeJSONPointer} from '../../utils/jsonPointer.js';
+import {buildPathLabel, buildHasPropertyToggle, readTriStateSelect} from '../searchUtils.js';
+import {combineAnd, makeHasPropertyLeaf} from '../queryTreeBuilders.js';
+import {
+  findSearchElement, getQueryViaElement, hasGetQuery
+} from '../searchElementUtils.js';
+import {buildSearchWidget} from '../searchDispatch.js';
+
+/**
+ * @typedef {import('../searchDispatch.js').SearchTypeObject} SearchTypeObject
+ */
+
+/**
+ * One added property's row: the fixed "has property" tri-state toggle
+ * (`buildHasPropertyToggle`) plus, immediately recursing (search plan §6
+ * build order: "Object / Array / Set - first types recursing into child
+ * schemas via `getSearchTypeObject`"), that property's own full search
+ * widget - so a user can combine "has property X" with "X matches Y" in
+ * one row rather than only being able to ask about existence.
+ * @param {{
+ *   propertyName: string,
+ *   propSchema: import('../../formats/schema.js').ZodexSchema,
+ *   path: string,
+ *   typeNamespace: string|undefined,
+ *   topRoot: import('../../types.js').RootElement|undefined,
+ *   types: import('../../types.js').default|undefined,
+ *   originalJSON: import('../../formats/schema.js').ZodexSchema|undefined
+ * }} cfg
+ * @returns {HTMLElement}
+ */
+function buildHasPropertyRow ({
+  propertyName, propSchema, path, typeNamespace, topRoot, types, originalJSON
+}) {
+  const childPath = `${path}/${escapeJSONPointer(propertyName)}`;
+  const name = `${typeNamespace}-hasProperty-${propertyName}`;
+  const childArr = buildSearchWidget({
+    schemaObject: propSchema, path: childPath, typeNamespace, topRoot, types,
+    originalJSON
+  });
+  return /** @type {HTMLElement} */ (jml('jsoe-search-has-property', {
+    dataset: {searchPath: childPath, searchKind: 'hasProperty', propertyName},
+    $define: {
+      // Reads `childPath` off `this.dataset` rather than closing over the
+      //   outer `path`/`propertyName`: `$define`'s mixin is installed once
+      //   on the shared prototype the first time this tag is defined, so
+      //   every later `<jsoe-search-has-property>` instance must read its
+      //   own per-row state off `this`. `readTriStateSelect`/
+      //   `findSearchElement` are themselves closure-free (class- and
+      //   `dataset`-driven; see `searchUtils.js`'s `findOwnControl`), so no
+      //   further per-instance state needs storing here.
+      /** @this {HTMLElement} */
+      getQuery () {
+        const searchPath = this.dataset.searchPath ?? '';
+        const existsCheck = readTriStateSelect(this);
+        const existsLeaf = existsCheck === undefined
+          ? undefined
+          : makeHasPropertyLeaf(searchPath, existsCheck);
+        const childEl = findSearchElement(this, searchPath);
+        const childLeaf = childEl && hasGetQuery(childEl)
+          ? childEl.getQuery()
+          : undefined;
+        return combineAnd([existsLeaf, childLeaf]);
+      }
+    }
+  }, [
+    buildHasPropertyToggle({name, propertyName}),
+    childArr
+  ]));
+}
+
+/**
+ * Has property &lt;property pull-down&gt; (README), additive: only
+ * optional properties are offered ("avoid listing required" - a required
+ * property is guaranteed present, so asking about its existence is
+ * meaningless), and picking one from the pull-down adds a row for it
+ * (removed from the pull-down so it can't be added twice); there is no
+ * remove affordance, since setting a row's toggle back to "(any)" already
+ * expresses "no constraint from this row" for the existence half, same as
+ * clearing the nested widget does for the value half.
+ * @type {SearchTypeObject}
+ */
+const objectSearchType = {
+  buildUI ({schemaObject, path, typeNamespace, topRoot, types, originalJSON}) {
+    const label = buildPathLabel(schemaObject, path);
+    const objectSchemaObject = /** @type {import('zodexy').SzObject} */ (
+      schemaObject
+    );
+    const availableProperties = Object.entries(
+      objectSchemaObject.properties
+    ).filter(([, propSchema]) => propSchema.isOptional === true);
+
+    return ['jsoe-search-object', {
+      dataset: {searchPath: path, searchKind: 'object'},
+      title: label,
+      $define: {
+        /** @this {HTMLElement} */
+        getQuery () {
+          const rows = [...this.children].filter(hasGetQuery);
+          return combineAnd(rows.map((row) => row.getQuery()));
+        }
+      }
+    }, [
+      ['div', {class: 'searchObjectControls'}, [
+        ['span', {class: 'searchLabel'}, [label]],
+        availableProperties.length
+          ? ['label', [
+            'Add property: ',
+            ['select', {class: 'addPropertySelect'}, [
+              ['option', {value: ''}, ['(choose a property)']],
+              ...availableProperties.map(([propertyName]) => (
+                ['option', {value: propertyName}, [propertyName]]
+              ))
+            ]]
+          ]]
+          : ['span', ['(no optional properties to search on)']],
+        ['button', {
+          type: 'button',
+          $on: {
+            click () {
+              const container = this.closest('jsoe-search-object');
+              const select = /** @type {HTMLSelectElement|null} */ (
+                container?.querySelector('select.addPropertySelect')
+              );
+              const propertyName = select?.value;
+              if (!container || !select || !propertyName) {
+                return;
+              }
+              const propSchema = objectSchemaObject.properties[propertyName];
+              const row = buildHasPropertyRow({
+                propertyName, propSchema, path, typeNamespace, topRoot, types,
+                originalJSON
+              });
+              container.append(row);
+              const option = select.querySelector(
+                `option[value="${CSS.escape(propertyName)}"]`
+              );
+              option?.remove();
+            }
+          }
+        }, ['Add']]
+      ]]
+    ]];
+  },
+  getQuery: getQueryViaElement
+};
+
+export default objectSearchType;

package/src/search/fundamentalTypes/promiseSearchType.js

@@ -0,0 +1,61 @@
+import {buildPathLabel} from '../searchUtils.js';
+import {makePassThroughLeaf} from '../queryTreeBuilders.js';
+import {findSearchElement, getQueryViaElement, hasGetQuery} from '../searchElementUtils.js';
+import {buildSearchWidget} from '../searchDispatch.js';
+
+/**
+ * @typedef {import('../searchDispatch.js').SearchTypeObject} SearchTypeObject
+ */
+
+/**
+ * Promise, Literal, catch: pass on children (README) - a promise wraps
+ * exactly one value at the same conceptual path (no path segment to add,
+ * unlike array's `*`/record's `*key`/`*value`), so this recurses into
+ * `.value`'s own search widget and wraps whatever it produces in a
+ * `passThrough` leaf (`queryTree.js`) purely so the tree keeps visible that
+ * the leaf was reached through a promise, rather than returning the child's
+ * leaf bare. ("Literal" needs no module of its own: `getSearchSchemaType`
+ * already resolves a `literal` schema straight to its value's own type via
+ * `getSchemaType`, e.g. a literal string dispatches to `stringSearchType.js`
+ * unchanged).
+ * @type {SearchTypeObject}
+ */
+const promiseSearchType = {
+  buildUI ({schemaObject, path, typeNamespace, topRoot, types, originalJSON}) {
+    const label = buildPathLabel(schemaObject, path);
+    const promiseSchemaObject = /** @type {import('zodexy').SzPromise} */ (
+      schemaObject
+    );
+    const childArr = buildSearchWidget({
+      schemaObject: promiseSchemaObject.value,
+      path,
+      typeNamespace,
+      topRoot,
+      types,
+      originalJSON
+    });
+    return ['jsoe-search-promise', {
+      dataset: {searchPath: path, searchKind: 'promise'},
+      title: label,
+      $define: {
+        /** @this {HTMLElement} */
+        getQuery () {
+          const searchPath = this.dataset.searchPath ?? '';
+          const childEl = findSearchElement(this, searchPath);
+          const childQuery = childEl && hasGetQuery(childEl)
+            ? childEl.getQuery()
+            : undefined;
+          return childQuery === undefined
+            ? undefined
+            : makePassThroughLeaf(searchPath, childQuery);
+        }
+      }
+    }, [
+      ['span', {class: 'searchLabel'}, [`${label} (resolved value)`]],
+      childArr
+    ]];
+  },
+  getQuery: getQueryViaElement
+};
+
+export default promiseSearchType;

package/src/search/fundamentalTypes/regexpSearchType.js

@@ -0,0 +1,48 @@
+import {buildPathLabel, buildLiteralRegexControls, readLiteralRegexQuery, buildMultiSelect, readMultiSelect} from '../searchUtils.js';
+import {makeMultiSelectLeaf, combineAnd} from '../queryTreeBuilders.js';
+import {getQueryViaElement} from '../searchElementUtils.js';
+import regexpType from '../../fundamentalTypes/regexpType.js';
+
+/**
+ * @typedef {import('../searchDispatch.js').SearchTypeObject} SearchTypeObject
+ */
+
+/**
+ * Regexp (source): OR literal or regex search/Does Not contain search, plus
+ * a multiple-select search of flags (README). `regexpType.js`'s own
+ * `allowedFlags` list is imported as-is for the flags control (search plan
+ * §4 - already a plain exported property, no extraction needed).
+ * @type {SearchTypeObject}
+ */
+const regexpSearchType = {
+  buildUI ({schemaObject, path, typeNamespace}) {
+    const label = buildPathLabel(schemaObject, path);
+    const name = `${typeNamespace}-regexp`;
+    return ['jsoe-search-regexp', {
+      dataset: {searchPath: path, searchKind: 'regexp'},
+      title: label,
+      $define: {
+        /** @this {HTMLElement} */
+        getQuery () {
+          const searchPath = this.dataset.searchPath ?? '';
+          const sourceLeaf = readLiteralRegexQuery(this, searchPath);
+          const selectedFlags = readMultiSelect(this);
+          const flagsLeaf = selectedFlags.length
+            ? makeMultiSelectLeaf(searchPath, {$in: selectedFlags})
+            : undefined;
+          return combineAnd([sourceLeaf, flagsLeaf]);
+        }
+      }
+    }, [
+      ['span', {class: 'searchLabel'}, [`${label} (source)`]],
+      buildLiteralRegexControls({name}),
+      ['label', [
+        'Flags: ',
+        buildMultiSelect({name: `${name}-flags`, options: regexpType.allowedFlags})
+      ]]
+    ]];
+  },
+  getQuery: getQueryViaElement
+};
+
+export default regexpSearchType;

package/src/search/fundamentalTypes/setSearchType.js

@@ -0,0 +1,65 @@
+import {buildPathLabel, buildLengthSizeControls, readLengthSizeQuery} from '../searchUtils.js';
+import {combineAnd} from '../queryTreeBuilders.js';
+import {findSearchElement, getQueryViaElement, hasGetQuery} from '../searchElementUtils.js';
+import {buildSearchWidget} from '../searchDispatch.js';
+
+/**
+ * @typedef {import('../searchDispatch.js').SearchTypeObject} SearchTypeObject
+ */
+
+/**
+ * Has length/size of <number> (README) - no sparse toggle: unlike
+ * `array`, a `Set` cannot have holes. Also recurses into the value schema's
+ * own search widget (as `arraySearchType.js` does for its element), via the
+ * same `*` path-segment convention (`queryTree.js`).
+ * @type {SearchTypeObject}
+ */
+const setSearchType = {
+  buildUI ({schemaObject, path, typeNamespace, topRoot, types, originalJSON}) {
+    const label = buildPathLabel(schemaObject, path);
+    const name = `${typeNamespace}-set`;
+    const setSchemaObject = /** @type {import('zodexy').SzSet} */ (
+      schemaObject
+    );
+    const elementPath = `${path}/*`;
+    const elementArr = buildSearchWidget({
+      schemaObject: setSchemaObject.value,
+      path: elementPath,
+      typeNamespace,
+      topRoot,
+      types,
+      originalJSON
+    });
+    return ['jsoe-search-set', {
+      dataset: {searchPath: path, searchKind: 'set'},
+      title: label,
+      $define: {
+        /** @this {HTMLElement} */
+        getQuery () {
+          const searchPath = this.dataset.searchPath ?? '';
+          const lengthLeaf = readLengthSizeQuery(this, searchPath);
+          const elementEl = findSearchElement(this, `${searchPath}/*`);
+          const elementLeaf = elementEl && hasGetQuery(elementEl)
+            ? elementEl.getQuery()
+            : undefined;
+          return combineAnd([lengthLeaf, elementLeaf]);
+        }
+      }
+    }, [
+      ['span', {class: 'searchLabel'}, [label]],
+      ...buildLengthSizeControls({
+        name,
+        min: setSchemaObject.minSize,
+        max: setSchemaObject.maxSize,
+        includeSparse: false
+      }),
+      ['div', {class: 'searchSetElement'}, [
+        ['span', ['Element matches: ']],
+        elementArr
+      ]]
+    ]];
+  },
+  getQuery: getQueryViaElement
+};
+
+export default setSearchType;

package/src/search/fundamentalTypes/stringSearchType.js

@@ -0,0 +1,35 @@
+import {buildPathLabel, buildLiteralRegexControls, readLiteralRegexQuery} from '../searchUtils.js';
+import {getQueryViaElement} from '../searchElementUtils.js';
+
+/**
+ * @typedef {import('../searchDispatch.js').SearchTypeObject} SearchTypeObject
+ */
+
+/**
+ * OR literal or regex search/Does Not contain search (README; also covers
+ * `StringObject` and `templateLiteral`, aliased to this same module in
+ * `searchDispatch.js` since the query semantics are identical).
+ * @type {SearchTypeObject}
+ */
+const stringSearchType = {
+  buildUI ({schemaObject, path, typeNamespace}) {
+    const label = buildPathLabel(schemaObject, path);
+    const name = `${typeNamespace}-string`;
+    return ['jsoe-search-string', {
+      dataset: {searchPath: path, searchKind: 'string'},
+      title: label,
+      $define: {
+        /** @this {HTMLElement} */
+        getQuery () {
+          return readLiteralRegexQuery(this, this.dataset.searchPath ?? '');
+        }
+      }
+    }, [
+      ['span', {class: 'searchLabel'}, [label]],
+      buildLiteralRegexControls({name})
+    ]];
+  },
+  getQuery: getQueryViaElement
+};
+
+export default stringSearchType;

package/src/search/fundamentalTypes/symbolSearchType.js

@@ -0,0 +1,38 @@
+import {buildPathLabel, buildLiteralRegexControls, readLiteralRegexQuery} from '../searchUtils.js';
+import {getQueryViaElement} from '../searchElementUtils.js';
+
+/**
+ * @typedef {import('../searchDispatch.js').SearchTypeObject} SearchTypeObject
+ */
+
+/**
+ * Symbol (description): OR literal or regex search/Does Not contain search
+ * (README) - the same query semantics as `stringSearchType.js`'s, against
+ * the symbol's description rather than a string value, so it gets its own
+ * dedicated module/tag (matching the value-editing side's one-file-per-
+ * fundamental-type convention) while sharing that module's actual control
+ * building/reading via `searchUtils.js`.
+ * @type {SearchTypeObject}
+ */
+const symbolSearchType = {
+  buildUI ({schemaObject, path, typeNamespace}) {
+    const label = buildPathLabel(schemaObject, path);
+    const name = `${typeNamespace}-symbol`;
+    return ['jsoe-search-symbol', {
+      dataset: {searchPath: path, searchKind: 'symbol'},
+      title: label,
+      $define: {
+        /** @this {HTMLElement} */
+        getQuery () {
+          return readLiteralRegexQuery(this, this.dataset.searchPath ?? '');
+        }
+      }
+    }, [
+      ['span', {class: 'searchLabel'}, [`${label} (description)`]],
+      buildLiteralRegexControls({name})
+    ]];
+  },
+  getQuery: getQueryViaElement
+};
+
+export default symbolSearchType;

package/src/search/fundamentalTypes/undefinedSearchType.js

@@ -0,0 +1,11 @@
+import {makePresenceOnlySearchType} from '../searchElementUtils.js';
+
+/**
+ * `undefined`/`void`: "no variants to allow for distinct search" (README).
+ * @type {import('../searchDispatch.js').SearchTypeObject}
+ */
+const undefinedSearchType = makePresenceOnlySearchType({
+  tagName: 'jsoe-search-undefined'
+});
+
+export default undefinedSearchType;

package/src/search/index.js

@@ -0,0 +1,79 @@
+import {jml} from '../vendor-imports.js';
+import {getSearchTypeObject, buildSearchWidget, resolveIntersection} from './searchDispatch.js';
+
+/**
+ * @typedef {{
+ *   container: HTMLDivElement,
+ *   $getQuery: () => import('./queryTree.js').QueryAnd,
+ *   whenReady: Promise<void>
+ * }} SearchChoicesControl
+ */
+
+/**
+ * The top-level entry point (search plan §5): builds the whole recursive
+ * search widget tree for `schemaContent` via `buildSearchWidget`
+ * (`searchDispatch.js`), starting at `path = '#/'`. Does not route through
+ * `getTypesForSchema` for the general case - that function flattens union
+ * members into one flat `Set` of leaf types for a type-choice pull-down,
+ * whereas search needs union branches to stay distinguishable nested
+ * sub-widgets for the "has type" affordance (`unionSearchType.js` et al.) -
+ * `getTypesForSchema` is only reused narrowly, for intersection resolution,
+ * inside `buildSearchWidget`/`resolveIntersection` - which run at *every*
+ * recursive call site (every composite module's own child recursion uses
+ * `buildSearchWidget` too), not just here at the root, so an intersection
+ * schema nested anywhere in the tree resolves the same way a top-level one
+ * does rather than falling through to the `noneditableSearchType` escape
+ * hatch.
+ *
+ * `resolveIntersection` is called here too (redundantly, but cheaply, since
+ * it's a no-op for anything that isn't itself an `intersection`) purely so
+ * `$getQuery()` below dispatches through the *same* resolved schema
+ * `buildSearchWidget` actually built the UI for, rather than the original
+ * (possibly-`intersection`) one.
+ *
+ * Mirrors `buildTypeChoices`'s (`src/typeChoices.js`) `whenReady`/
+ * pull-based convention rather than inventing a push/callback API:
+ * `$getQuery()` reads the live DOM into a `QueryAnd` on demand (`{$and:
+ * []}` when nothing has been entered anywhere, matching the empty-`$and`
+ * convention of "no constraint"), and a host that wants live updates wraps
+ * it in its own `container.addEventListener('input', ...)` since
+ * `container` is a plain `HTMLDivElement`. Every widget built so far is
+ * synchronous, so `whenReady` (unlike `buildTypeChoices`'s) has no deferred
+ * work to wait on and settles immediately - it's still returned, so a
+ * caller can `await` either function uniformly without checking which one
+ * it has.
+ * @param {{
+ *   schemaContent: import('../formats/schema.js').ZodexSchema,
+ *   typeNamespace?: string,
+ *   topRoot?: import('../types.js').RootElement,
+ *   types?: import('../types.js').default
+ * }} cfg
+ * @returns {SearchChoicesControl}
+ */
+export function buildSearchChoices ({schemaContent, typeNamespace, topRoot, types}) {
+  // Not '#/': `getJSONPointerParts` (`src/utils/jsonPointer.js`) splits on
+  //   '/' and drops the leading '#', so '#/' parts to `['']` (one segment
+  //   named the empty string) rather than `[]` (the root, no segments yet)
+  //   - every recursive module here appends `${path}/segment`, so starting
+  //   from the bare '#' is what keeps the first level from coming out as
+  //   '#//segment'.
+  const path = '#';
+  const arr = buildSearchWidget({
+    schemaObject: schemaContent, path, typeNamespace, topRoot, types,
+    originalJSON: schemaContent
+  });
+  const container = /** @type {HTMLDivElement} */ (
+    jml('div', {class: 'searchChoicesContainer'}, [arr])
+  );
+  const schemaObject = resolveIntersection(schemaContent, schemaContent);
+  return {
+    container,
+    $getQuery () {
+      const result = getSearchTypeObject(schemaObject).getQuery({
+        root: container, path
+      });
+      return {$and: result === undefined ? [] : [result]};
+    },
+    whenReady: Promise.resolve()
+  };
+}