@es-joy/jsoe 0.28.2 → 0.30.0

package/src/search/subTypes/blobHTMLSearchType.js

@@ -0,0 +1,122 @@
+import {
+  buildPathLabel, findOwnControl, isExemptedByAncestorHasProperty
+} from '../searchUtils.js';
+import {makeBlobHTMLLeaf} from '../queryTreeBuilders.js';
+import {getQueryViaElement} from '../searchElementUtils.js';
+
+/**
+ * @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}
+ */
+const blobHTMLSearchType = {
+  buildUI ({schemaObject, path, typeNamespace}) {
+    const label = buildPathLabel(schemaObject, path);
+    const name = `${typeNamespace}-blobHTML`;
+    return ['jsoe-search-blob-html', {
+      dataset: {searchPath: path, searchKind: 'blobHTML'},
+      title: label,
+      $define: {
+        /** @this {HTMLElement} */
+        getQuery () {
+          const searchPath = this.dataset.searchPath ?? '';
+          const mode = /** @type {HTMLSelectElement|undefined} */ (
+            findOwnControl(this, 'select.jsoeSearchBlobHTMLMode')
+          )?.value;
+          const value = /** @type {HTMLInputElement|HTMLTextAreaElement|undefined} */ (
+            findOwnControl(
+              this,
+              `${mode === 'fullText' ? 'textarea' : 'input'}.jsoeSearchBlobHTMLValue`
+            )
+          )?.value;
+          if (!value || !mode) {
+            return undefined;
+          }
+          return makeBlobHTMLLeaf(
+            searchPath,
+            /** @type {import('../queryTree.js').QueryBlobHTMLLeaf['mode']} */ (mode),
+            value
+          );
+        }
+      }
+    }, [
+      ['span', {class: 'searchLabel'}, [label]],
+      ['label', [
+        'Mode: ',
+        ['select', {
+          name: `${name}-mode`,
+          class: 'jsoeSearchBlobHTMLMode',
+          $on: {
+            change () {
+              const container = this.closest('jsoe-search-blob-html');
+              const input = /** @type {HTMLInputElement|null|undefined} */ (
+                container?.querySelector('input.jsoeSearchBlobHTMLValue')
+              );
+              const textarea = /** @type {HTMLTextAreaElement|null|undefined} */ (
+                container?.querySelector('textarea.jsoeSearchBlobHTMLValue')
+              );
+              const isFullText = /** @type {HTMLSelectElement} */ (this).value ===
+                'fullText';
+              const exempted = container !== null &&
+                isExemptedByAncestorHasProperty(container);
+              if (input) {
+                input.hidden = isFullText;
+                input.required = !isFullText && !exempted;
+              }
+              if (textarea) {
+                textarea.hidden = !isFullText;
+                textarea.required = isFullText && !exempted;
+              }
+            }
+          }
+        }, [
+          ['option', {value: 'xpath'}, ['XPath']],
+          ['option', {value: 'cssSelector'}, ['CSS selector']],
+          ['option', {value: 'fullText'}, ['Full text search']],
+          ['option', {value: 'rawHTMLRegex'}, ['Regex search of raw HTML']]
+        ]]
+      ]],
+      ['label', [
+        'Value: ',
+        ['input', {
+          type: 'text', name: `${name}-value`, class: 'jsoeSearchBlobHTMLValue',
+          required: true
+        }],
+        ['textarea', {
+          name: `${name}-value`, class: 'jsoeSearchBlobHTMLValue', hidden: true
+        }]
+      ]]
+    ]];
+  },
+  getQuery: getQueryViaElement
+};
+
+export default blobHTMLSearchType;

package/src/search/subTypes/recordSearchType.js

@@ -0,0 +1,105 @@
+import {
+  buildPathLabel, buildCheckbox, readCheckbox, buildOptInFieldset,
+  readOptInChecked, wireOptInFieldset, buildAtLeastOneSentinel, syncAtLeastOneCheck
+} from '../searchUtils.js';
+import {makeMapRecordJointLeaf} from '../queryTreeBuilders.js';
+import {findSearchElement, getQueryViaElement, hasGetQuery} from '../searchElementUtils.js';
+import {buildSearchWidget} from '../searchDispatch.js';
+
+/**
+ * @typedef {import('../searchDispatch.js').SearchTypeObject} SearchTypeObject
+ */
+
+/**
+ * @param {Element} root - a `jsoe-search-record` element
+ * @returns {void}
+ */
+function syncKeyValueValidity (root) {
+  syncAtLeastOneCheck(
+    root, () => readOptInChecked(root, 'key') || readOptInChecked(root, 'value')
+  );
+}
+
+/**
+ * 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}
+ */
+const recordSearchType = {
+  buildUI ({schemaObject, path, typeNamespace, topRoot, types, originalJSON}) {
+    const label = buildPathLabel(schemaObject, path);
+    const name = `${typeNamespace}-record`;
+    const recordSchemaObject = /** @type {import('zodexy').SzRecord} */ (
+      schemaObject
+    );
+    const keyPath = `${path}/*key`;
+    const valuePath = `${path}/*value`;
+    const keyArr = buildSearchWidget({
+      schemaObject: recordSchemaObject.key,
+      path: keyPath,
+      typeNamespace,
+      topRoot,
+      types,
+      originalJSON
+    });
+    const valueArr = buildSearchWidget({
+      schemaObject: recordSchemaObject.value,
+      path: valuePath,
+      typeNamespace,
+      topRoot,
+      types,
+      originalJSON
+    });
+    return ['jsoe-search-record', {
+      dataset: {searchPath: path, searchKind: 'record'},
+      title: label,
+      $define: {
+        /** @this {HTMLElement} */
+        connectedCallback () {
+          wireOptInFieldset(this, 'key', () => syncKeyValueValidity(this));
+          wireOptInFieldset(this, 'value', () => syncKeyValueValidity(this));
+          syncKeyValueValidity(this);
+        },
+        /** @this {HTMLElement} */
+        getQuery () {
+          const searchPath = this.dataset.searchPath ?? '';
+          const keyEl = findSearchElement(this, `${searchPath}/*key`);
+          const valueEl = findSearchElement(this, `${searchPath}/*value`);
+          const keyQuery = keyEl && hasGetQuery(keyEl) && readOptInChecked(this, 'key')
+            ? keyEl.getQuery()
+            : undefined;
+          const valueQuery = valueEl && hasGetQuery(valueEl) && readOptInChecked(this, 'value')
+            ? valueEl.getQuery()
+            : undefined;
+          if (!keyQuery && !valueQuery) {
+            return undefined;
+          }
+          const joint = readCheckbox(this);
+          return makeMapRecordJointLeaf(searchPath, joint, keyQuery, valueQuery);
+        }
+      }
+    }, [
+      ['span', {class: 'searchLabel'}, [label]],
+      ...buildOptInFieldset({
+        name: `${name}-key`, key: 'key', label: 'Key matches', children: [keyArr]
+      }),
+      ...buildOptInFieldset({
+        name: `${name}-value`, key: 'value', label: 'Value matches', children: [valueArr]
+      }),
+      buildCheckbox({name: `${name}-joint`, label: 'Require same entry'}),
+      buildAtLeastOneSentinel()
+    ]];
+  },
+  getQuery: getQueryViaElement
+};
+
+export default recordSearchType;

package/src/search/subTypes/tupleSearchType.js

@@ -0,0 +1,152 @@
+import {
+  buildPathLabel, buildLengthSizeControls, readLengthSizeQuery,
+  buildOptInFieldset, readOptInChecked, wireOptInFieldset,
+  buildAtLeastOneSentinel, syncAtLeastOneCheck
+} 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
+ */
+
+/**
+ * @param {Element} root - a `jsoe-search-tuple` element
+ * @returns {void}
+ */
+function syncTupleValidity (root) {
+  const itemCount = Number(/** @type {HTMLElement} */ (root).dataset.itemCount ?? '0');
+  const hasRest = /** @type {HTMLElement} */ (root).dataset.hasRest === 'true';
+  syncAtLeastOneCheck(root, () => (
+    Array.from({length: itemCount}, (_, idx) => String(idx)).some(
+      (key) => readOptInChecked(root, key)
+    ) ||
+    (hasRest && (readOptInChecked(root, 'rest') || readLengthSizeQuery(root, '') !== undefined))
+  ));
+}
+
+/**
+ * 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}
+ */
+const tupleSearchType = {
+  buildUI ({schemaObject, path, typeNamespace, topRoot, types, originalJSON}) {
+    const label = buildPathLabel(schemaObject, path);
+    const name = `${typeNamespace}-tuple`;
+    const tupleSchemaObject = /** @type {import('zodexy').SzTuple} */ (
+      schemaObject
+    );
+    const {items, rest} = tupleSchemaObject;
+
+    const itemArrs = items.map((itemSchema, idx) => buildSearchWidget({
+      schemaObject: itemSchema,
+      path: `${path}/${idx}`,
+      typeNamespace,
+      topRoot,
+      types,
+      originalJSON
+    }));
+
+    const restElementPath = `${path}/*`;
+    const restArr = rest
+      ? buildSearchWidget({
+        schemaObject: rest,
+        path: restElementPath,
+        typeNamespace,
+        topRoot,
+        types,
+        originalJSON
+      })
+      : undefined;
+
+    /** @type {import('../../types.js').JamilihArray[]} */
+    const children = [['span', {class: 'searchLabel'}, [label]]];
+    itemArrs.forEach((itemArr, idx) => {
+      children.push(...buildOptInFieldset({
+        name: `${name}-${idx}`, key: String(idx), label: `Position ${idx} matches`,
+        children: [itemArr]
+      }));
+    });
+    if (rest) {
+      const restChild = /** @type {import('../../types.js').JamilihArray} */ (restArr);
+      children.push(
+        ...buildLengthSizeControls({
+          name, min: items.length, max: undefined, includeSparse: false
+        }),
+        ...buildOptInFieldset({
+          name: `${name}-rest`, key: 'rest', label: 'Rest element matches',
+          children: [restChild]
+        })
+      );
+    }
+    children.push(buildAtLeastOneSentinel());
+
+    return ['jsoe-search-tuple', {
+      dataset: {
+        searchPath: path, searchKind: 'tuple',
+        itemCount: String(items.length), hasRest: rest ? 'true' : ''
+      },
+      title: label,
+      $define: {
+        // Reads `itemCount`/`hasRest` off `this.dataset` rather than
+        //   closing over `items`/`rest`: `$define`'s mixin is installed
+        //   once on the shared prototype the first time this tag is
+        //   defined, so a second tuple widget on the same page would
+        //   otherwise silently reuse the first tuple's item count/rest-ness.
+        /** @this {HTMLElement} */
+        connectedCallback () {
+          const itemCount = Number(this.dataset.itemCount ?? '0');
+          Array.from({length: itemCount}, (_, idx) => String(idx)).forEach(
+            (key) => wireOptInFieldset(this, key, () => syncTupleValidity(this))
+          );
+          if (this.dataset.hasRest === 'true') {
+            wireOptInFieldset(this, 'rest', () => syncTupleValidity(this));
+            this.querySelector('input.jsoeSearchSize')?.addEventListener(
+              'input', () => syncTupleValidity(this)
+            );
+          }
+          syncTupleValidity(this);
+        },
+        /** @this {HTMLElement} */
+        getQuery () {
+          const searchPath = this.dataset.searchPath ?? '';
+          const itemCount = Number(this.dataset.itemCount ?? '0');
+          const hasRest = this.dataset.hasRest === 'true';
+          const itemLeaves = Array.from({length: itemCount}, (_, idx) => {
+            if (!readOptInChecked(this, String(idx))) {
+              return undefined;
+            }
+            const itemEl = findSearchElement(this, `${searchPath}/${idx}`);
+            return itemEl && hasGetQuery(itemEl) ? itemEl.getQuery() : undefined;
+          });
+          if (!hasRest) {
+            return combineAnd(itemLeaves);
+          }
+          const lengthLeaf = readLengthSizeQuery(this, searchPath);
+          const restEl = findSearchElement(this, `${searchPath}/*`);
+          const restLeaf = restEl && hasGetQuery(restEl) && readOptInChecked(this, 'rest')
+            ? restEl.getQuery()
+            : undefined;
+          return combineAnd([...itemLeaves, lengthLeaf, restLeaf]);
+        }
+      }
+    }, children];
+  },
+  getQuery: getQueryViaElement
+};
+
+export default tupleSearchType;

package/src/search/superTypes/SpecialRealNumberSearchType.js

@@ -0,0 +1,42 @@
+import {buildPathLabel, buildMultiSelect, readMultiSelect} from '../searchUtils.js';
+import {makeMultiSelectLeaf} from '../queryTreeBuilders.js';
+import {getQueryViaElement} from '../searchElementUtils.js';
+
+/**
+ * @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}
+ */
+const SpecialRealNumberSearchType = {
+  buildUI ({schemaObject, path, typeNamespace}) {
+    const label = buildPathLabel(schemaObject, path);
+    const name = `${typeNamespace}-SpecialRealNumber`;
+    return ['jsoe-search-special-real-number', {
+      dataset: {searchPath: path, searchKind: 'SpecialRealNumber'},
+      title: label,
+      $define: {
+        /** @this {HTMLElement} */
+        getQuery () {
+          const selected = readMultiSelect(this);
+          return selected.length
+            ? makeMultiSelectLeaf(this.dataset.searchPath ?? '', {$in: selected})
+            : undefined;
+        }
+      }
+    }, [
+      ['span', {class: 'searchLabel'}, [label]],
+      buildMultiSelect({
+        name, options: ['Infinity', '-Infinity', '-0'], required: true
+      })
+    ]];
+  },
+  getQuery: getQueryViaElement
+};
+
+export default SpecialRealNumberSearchType;

package/src/search/superTypes/buffersourceSearchType.js

@@ -0,0 +1,53 @@
+import {
+  buildPathLabel, buildRangeInputsPair, readRangeInputsPair, syncRangeValidity
+} from '../searchUtils.js';
+import {makeRangeLeaf} from '../queryTreeBuilders.js';
+import {getQueryViaElement} from '../searchElementUtils.js';
+
+/**
+ * @typedef {import('../searchDispatch.js').SearchTypeObject} SearchTypeObject
+ */
+
+/**
+ * BufferSource: OR Range/Is Not Range (README) - a byte-length range, per
+ * the build order's own note that `buffersource` (like `function`) is
+ * "fuzzy" enough in the README to ship as a minimal, honest stub rather
+ * than over-build past what the spec defines. `buffersource` is one of
+ * jsoe's "checked" types (`{type: 'any', checks: [{name: 'buffersource'}]}`)
+ * with no schema-level byte-length bounds to read `min`/`max` HTML
+ * attributes from, unlike `array`'s `minLength`/`maxLength`.
+ * @type {SearchTypeObject}
+ */
+const buffersourceSearchType = {
+  buildUI ({schemaObject, path, typeNamespace}) {
+    const label = buildPathLabel(schemaObject, path);
+    const name = `${typeNamespace}-buffersource`;
+    return ['jsoe-search-buffersource', {
+      dataset: {searchPath: path, searchKind: 'buffersource'},
+      title: label,
+      $define: {
+        /** @this {HTMLElement} */
+        connectedCallback () {
+          syncRangeValidity(this);
+        },
+        /** @this {HTMLElement} */
+        getQuery () {
+          const {gte, lte} = readRangeInputsPair(this);
+          if (gte === '' && lte === '') {
+            return undefined;
+          }
+          return makeRangeLeaf(this.dataset.searchPath ?? '', 'buffersource', {
+            ...(gte === '' ? {} : {$gte: Number(gte)}),
+            ...(lte === '' ? {} : {$lte: Number(lte)})
+          });
+        }
+      }
+    }, [
+      ['span', {class: 'searchLabel'}, [`${label} (byte length)`]],
+      ...buildRangeInputsPair({name, min: 0})
+    ]];
+  },
+  getQuery: getQueryViaElement
+};
+
+export default buffersourceSearchType;

package/src/search/superTypes/dommatrixSearchType.js

@@ -0,0 +1,24 @@
+import {makeDomShapeSearchType} from '../searchElementUtils.js';
+
+/**
+ * DOMMatrix: numeric search ranges for children; "Is/Is not Readonly";
+ * "Is/Is not 3d" (README) - see `searchElementUtils.js`'s
+ * `makeDomShapeSearchType` for the shared implementation. `dimensionKeys`
+ * covers both the 2D (`a`-`f`) and 3D (`m11`-`m44`) property sets at once;
+ * see that factory's doc for why.
+ * @type {import('../searchDispatch.js').SearchTypeObject}
+ */
+const dommatrixSearchType = makeDomShapeSearchType({
+  tagName: 'jsoe-search-dommatrix',
+  dimensionKeys: [
+    'a', 'b', 'c', 'd', 'e', 'f',
+    'm11', 'm12', 'm13', 'm14',
+    'm21', 'm22', 'm23', 'm24',
+    'm31', 'm32', 'm33', 'm34',
+    'm41', 'm42', 'm43', 'm44'
+  ],
+  includeReadonly: true,
+  includeDimensionCheck: true
+});
+
+export default dommatrixSearchType;

package/src/search/superTypes/dompointSearchType.js

@@ -0,0 +1,15 @@
+import {makeDomShapeSearchType} from '../searchElementUtils.js';
+
+/**
+ * DOMPoint: numeric search ranges for children; "Is/Is not Readonly"
+ * (README) - see `searchElementUtils.js`'s `makeDomShapeSearchType` for the
+ * shared implementation.
+ * @type {import('../searchDispatch.js').SearchTypeObject}
+ */
+const dompointSearchType = makeDomShapeSearchType({
+  tagName: 'jsoe-search-dompoint',
+  dimensionKeys: ['x', 'y', 'z', 'w'],
+  includeReadonly: true
+});
+
+export default dompointSearchType;

package/src/search/superTypes/domrectSearchType.js

@@ -0,0 +1,15 @@
+import {makeDomShapeSearchType} from '../searchElementUtils.js';
+
+/**
+ * DOMRect: numeric search ranges for children; "Is/Is not Readonly"
+ * (README) - see `searchElementUtils.js`'s `makeDomShapeSearchType` for the
+ * shared implementation.
+ * @type {import('../searchDispatch.js').SearchTypeObject}
+ */
+const domrectSearchType = makeDomShapeSearchType({
+  tagName: 'jsoe-search-domrect',
+  dimensionKeys: ['x', 'y', 'width', 'height'],
+  includeReadonly: true
+});
+
+export default domrectSearchType;

package/src/search/superTypes/errorsSpecialSearchType.js

@@ -0,0 +1,15 @@
+import {makeErrorFamilySearchType} from '../searchElementUtils.js';
+
+/**
+ * Special Errors (RangeError/TypeError/SyntaxError/AggregateError/etc.):
+ * Literal/Regex search of child string properties, numeric of number
+ * children (README, same bullet as plain `Error`) - see
+ * `searchElementUtils.js`'s `makeErrorFamilySearchType` for the shared
+ * implementation.
+ * @type {import('../searchDispatch.js').SearchTypeObject}
+ */
+const errorsSpecialSearchType = makeErrorFamilySearchType({
+  tagName: 'jsoe-search-errors-special'
+});
+
+export default errorsSpecialSearchType;

package/src/search/unions/discriminatedUnionSearchType.js

@@ -0,0 +1,16 @@
+import {makeUnionFamilySearchType} from './unionFamilySearchType.js';
+
+/**
+ * Discriminated Union: "Has type <type pull-down>", using the
+ * discriminator of discriminated union (README) - the type pull-down's
+ * options are labelled by each branch's discriminator value (e.g.
+ * `'circle'`/`'square'`) rather than a generic type name, and the resulting
+ * `typeOf` leaf carries that value too (`queryTree.js`). See
+ * `unionFamilySearchType.js` for the shared implementation.
+ * @type {import('../searchDispatch.js').SearchTypeObject}
+ */
+const discriminatedUnionSearchType = makeUnionFamilySearchType({
+  tagName: 'jsoe-search-discriminated-union', discriminated: true
+});
+
+export default discriminatedUnionSearchType;