@es-joy/jsoe 0.24.3 → 0.25.1

package/src/typeChoices.js

@@ -3,7 +3,35 @@ import Formats from './formats.js';
 import Types from './types.js';
 
 import {$e, DOM} from './utils/templateUtils.js';
+import {isUnionLike} from './utils/types.js';
+import {getXorBranchMatchInfo, valueMatchesSchema} from './formats/schema.js';
 import dialogs from './utils/dialogs.js';
+import {tick} from './utils/timing.js';
+import deepEqual from 'fast-deep-equal/es6/index.js';
+
+/**
+ * A deferred `setValue`/auto-select runs a tick after the control is built, but
+ * the caller may only connect it to the document on a deferred tick of its own
+ * (e.g. `setTimeout(0)` DOM insertion). Wait this many ticks for the connection
+ * before giving up, rather than dropping the pre-set value on the first miss.
+ */
+const MAX_CONNECT_WAIT_TICKS = 50;
+
+/**
+ * @param {HTMLSelectElement} sel
+ * @returns {Promise<boolean>} Whether `sel` became connected within the bound.
+ */
+const waitForConnection = async (sel) => {
+  for (
+    let waited = 0;
+    !sel.isConnected && waited < MAX_CONNECT_WAIT_TICKS;
+    waited++
+  ) {
+    // eslint-disable-next-line no-await-in-loop -- Sequential by design
+    await tick();
+  }
+  return sel.isConnected;
+};
 
 // This is technically just `import('./index.js').SetType`, but our
 //   redirect file causes problems, so we redefine here
@@ -13,15 +41,30 @@ import dialogs from './utils/dialogs.js';
  *   baseValue?: import('./formats.js').StructuredCloneValue,
  *   bringIntoFocus?: boolean,
  *   avoidReport?: boolean,
- *   specificSchema?: import('zodex').SzType
+ *   specificSchema?: import('zodexy').SzType
  * }) => void} SetType
  */
 
 /**
  * @typedef {(info: {
  *   type: string,
- *   editUI: Element,
- *   specificSchema?: import('zodex').SzType
+ *   specificSchema?: import('zodexy').SzType
+ * }) => void} SetTypeNoEditUI
+ */
+/**
+ * @callback Validate
+ * @param {{avoidReport?: boolean}} cfg
+ * @returns {boolean}
+ */
+/**
+ * @typedef {() => false|null|HTMLElement} GetTypeRoot
+ */
+
+/**
+ * @typedef {(info: {
+ *   type: string,
+ *   editUI: HTMLElement,
+ *   specificSchema?: import('zodexy').SzType
  * }) => void} AddTypeAndEditUI
  */
 
@@ -39,9 +82,19 @@ import dialogs from './utils/dialogs.js';
  */
 
 /**
- * @typedef {HTMLElement & {
+ * @typedef {(info: {editUI: HTMLElement}) => void} AddEditUI
+ */
+
+/**
+ * @typedef {HTMLSelectElement & {
  *   $addAndValidateEditUI: AddAndValidateEditUI,
- *   $setStyles: SetStyles
+ *   $setStyles: SetStyles,
+ *   $getTypeRoot: GetTypeRoot,
+ *   $getContainer: () => HTMLElement,
+ *   $getTopRoot: () => HTMLDivElement,
+ *   $addEditUI: AddEditUI,
+ *   $validate: Validate,
+ *   $setTypeNoEditUI: SetTypeNoEditUI
  * }} TypeChoicesElementAPI
  */
 
@@ -100,6 +153,231 @@ import dialogs from './utils/dialogs.js';
  * }}
  */
 
+/**
+ * The `<select>`-shaped `$`-methods that downstream code invokes on a
+ * type-choices control. The `xor` radio group reuses these by reference from
+ * the parallel `<select>`.
+ * @type {readonly string[]}
+ */
+const typeChoicesAPIMethods = [
+  '$getValue', '$setType', '$setTypeNoEditUI', '$setStyles', '$getTypeRoot',
+  '$addAndValidateEditUI', '$addTypeAndEditUI', '$addEditUI', '$getContainer',
+  '$getTopRoot', '$validate'
+];
+
+/**
+ * Human-readable caption for one `xor` branch radio. Prefers the branch's own
+ * `description`; otherwise derives something legible from its shape so the
+ * branches can be told apart without reading schema.
+ * @param {import('zodexy').SzType|undefined} schemaObj
+ * @param {string} optText Fallback option text (already e.g. `"string"`)
+ * @param {number} idx
+ * @returns {string}
+ */
+function deriveXorBranchLabel (schemaObj, optText, idx) {
+  if (schemaObj && 'description' in schemaObj && schemaObj.description) {
+    return /** @type {string} */ (schemaObj.description);
+  }
+  if (schemaObj && schemaObj.type === 'literal') {
+    const {values} = /** @type {import('zodexy').SzLiteral<any>} */ (schemaObj);
+    if (Array.isArray(values) && values.length) {
+      return String(values[0]);
+    }
+  }
+  if (schemaObj && schemaObj.type === 'object') {
+    const {properties} = /** @type {import('zodexy').SzObject} */ (schemaObj);
+    const keys = properties && typeof properties === 'object'
+      ? Object.keys(properties)
+      : [];
+    if (keys.length) {
+      // Todo: when branches share property names, prefer the keys unique to
+      //   this branch (symmetric difference against its siblings)
+      return keys.length > 3
+        ? `${keys.slice(0, 3).join(', ')}, +${keys.length - 3} more`
+        : keys.join(', ');
+    }
+  }
+  return optText || `Option ${idx + 1}`;
+}
+
+/**
+ * Build the `xor` (exclusive union) radio-group control. It renders a
+ * labelled radio per branch and shims the `<select>` value surface
+ * (`value`, `selectedIndex`, `selectedOptions`), reusing the `$`-methods of
+ * the parallel `<select>` in `selectEl` by reference. A live indicator under
+ * the radios counts how many branches the current value satisfies, since
+ * `xor` requires exactly one and jsoe otherwise validates only the chosen
+ * branch's leaf schema.
+ * @param {{
+ *   typeNamespace: string|undefined,
+ *   keySelectClass: string|undefined,
+ *   typeOptions: [string, {value?: string, title?: string}?][],
+ *   schemaObjs: import('zodexy').SzType[],
+ *   types: InstanceType<typeof import('./types.js').default>,
+ *   typeContainer: HTMLElement,
+ *   xorSchema: import('zodexy').SzUnion|undefined,
+ *   selectEl: HTMLSelectElement
+ * }} cfg
+ * @returns {HTMLSelectElement}
+ */
+function buildXorTypeChoices ({
+  typeNamespace, keySelectClass, typeOptions, schemaObjs, types,
+  typeContainer, xorSchema, selectEl
+}) {
+  const radioName = `typeChoices-${typeNamespace}-xor`;
+  const fieldset = jml('fieldset', {
+    class: `typeChoices-${typeNamespace} xorTypeChoices${keySelectClass
+      ? ' ' + keySelectClass
+      : ''
+    }`,
+    $on: {change (e) {
+      e?.stopPropagation();
+      const idxAttr =
+        /** @type {HTMLElement} */ (e.target)?.dataset?.idx ??
+        /** @type {TypeChoicesElementAPI} */ (
+          this
+        ).selectedOptions[0]?.dataset?.idx;
+      /** @type {TypeChoicesElementAPI} */ (this).$addAndValidateEditUI({
+        schemaObject: idxAttr === undefined
+          ? undefined
+          : schemaObjs[Number(idxAttr)]
+      });
+      /** @type {TypeChoicesElementAPI} */ (this).$setStyles();
+      updateMatchStatus();
+    }}
+  }, [
+    ['legend', {class: 'xorTypeChoicesLegend'}, ['Exactly one of']],
+    ...typeOptions.map(([optText, optAtts], idx) => {
+      return ['label', {class: 'xorTypeChoice'}, [
+        ['input', {
+          type: 'radio',
+          name: radioName,
+          value: /** @type {string} */ (optAtts?.value ?? ''),
+          dataset: {idx}
+        }],
+        ['span', {class: 'xorTypeChoiceLabel'}, [
+          deriveXorBranchLabel(schemaObjs[idx], optText, idx)
+        ]]
+      ]];
+    }),
+    ['div', {class: 'xorMatchStatus', hidden: true}]
+  ]);
+
+  const radios = () => /** @type {HTMLInputElement[]} */ (
+    [...fieldset.querySelectorAll('input[type="radio"]')]
+  );
+
+  const matchStatus = /** @type {HTMLElement} */ (
+    $e(fieldset, '.xorMatchStatus')
+  );
+
+  /**
+   * Re-count how many `xor` branches the assembled value satisfies and
+   * reflect it in the indicator, also marking the chosen radio invalid when
+   * the count is not exactly one so the form's `checkValidity()` catches it.
+   * @returns {void}
+   */
+  function updateMatchStatus () {
+    // Only the currently-chosen branch's match state is meaningful; clear any
+    //   custom validity left on the other radios so a stale message from a
+    //   previously-selected branch does not keep the form invalid after the
+    //   user switches branches.
+    const allRadios = radios();
+    for (const r of allRadios) {
+      r.setCustomValidity('');
+    }
+    const checked = allRadios.find((r) => r.checked);
+    if (!xorSchema || !checked || !$e(typeContainer, 'div[data-type]')) {
+      matchStatus.hidden = true;
+      return;
+    }
+    let value;
+    try {
+      value = /** @type {() => unknown} */ (fsAPI.$getValue)();
+    } catch {
+      // Editor not ready or value not yet parseable
+      matchStatus.hidden = true;
+      return;
+    }
+    const {matched, total} = getXorBranchMatchInfo(types, xorSchema, value);
+    // The value must satisfy the branch the user actually chose, not merely
+    //   *some* branch: an empty value on the "email" branch still matches the
+    //   plain-`string` branch, so the count alone would call it valid.
+    const selectedSchema = schemaObjs[Number(checked.dataset.idx)];
+    const selectedMatches = Boolean(selectedSchema) &&
+      valueMatchesSchema(types, selectedSchema, value);
+    // Anything but "the chosen branch, and only it" is invalid — including a
+    //   still-empty branch (zero matches): the form must not be submittable
+    //   in that state, so we always show the indicator and set validity once
+    //   a branch is chosen.
+    const ok = selectedMatches && matched === 1;
+    matchStatus.hidden = false;
+    matchStatus.textContent = !selectedMatches
+      ? 'Value does not match the selected option'
+      : ok
+        ? `Matches 1 of ${total} options`
+        : `Matches ${matched} of ${total} — value must match exactly one`;
+    matchStatus.classList.toggle('xorMatchOk', ok);
+    matchStatus.classList.toggle('xorMatchErr', !ok);
+    checked.setCustomValidity(
+      ok
+        ? ''
+        : selectedMatches
+          ? 'Value must match exactly one option'
+          : 'Value does not match the selected option'
+    );
+  }
+
+  typeContainer.addEventListener('input', updateMatchStatus);
+  typeContainer.addEventListener('change', updateMatchStatus);
+
+  const selAPI = /** @type {Record<string, unknown>} */ (
+    /** @type {unknown} */ (selectEl)
+  );
+  const fsAPI = /** @type {Record<string, unknown>} */ (
+    /** @type {unknown} */ (fieldset)
+  );
+  for (const method of typeChoicesAPIMethods) {
+    fsAPI[method] = selAPI[method];
+  }
+
+  Object.defineProperties(fieldset, {
+    value: {
+      configurable: true,
+      get () {
+        return radios().find((r) => r.checked)?.value ?? '';
+      },
+      set (v) {
+        const match = radios().find((r) => r.value === v);
+        for (const r of radios()) {
+          r.checked = r === match;
+        }
+      }
+    },
+    selectedIndex: {
+      configurable: true,
+      get () {
+        const i = radios().findIndex((r) => r.checked);
+        return i === -1 ? 0 : i + 1;
+      },
+      set (i) {
+        radios().forEach((r, idx) => {
+          r.checked = idx === Number(i) - 1;
+        });
+      }
+    },
+    selectedOptions: {
+      configurable: true,
+      get () {
+        const r = radios().find((rd) => rd.checked);
+        return r ? [{value: r.value, dataset: {idx: r.dataset.idx}}] : [];
+      }
+    }
+  });
+
+  return /** @type {HTMLSelectElement} */ (/** @type {unknown} */ (fieldset));
+}
+
 /**
  * @type {BuildTypeChoices}
  */
@@ -152,7 +430,11 @@ export const buildTypeChoices = ({
       currentPath
     );
   };
-  const sel = /** @type {HTMLSelectElement} */ (jml('select', {
+  // Created before the control so the `xor` radio group can bind its live
+  //   match indicator to value changes inside it
+  const typeContainer = jml('div', {class: 'typeContainer'});
+
+  const selectEl = /** @type {HTMLSelectElement} */ (jml('select', {
     hidden: requireObject || typeOptions.length === 1,
     class: `typeChoices-${typeNamespace}${keySelectClass
       ? ' ' + keySelectClass
@@ -161,14 +443,18 @@ export const buildTypeChoices = ({
     // is: 'type-choices',
     $custom: {
       $getValue,
-      /** @type {SetType} */
-      $setType ({
-        type, baseValue, bringIntoFocus, avoidReport, specificSchema
-      }) {
+      /**
+       * @this {TypeChoicesElementAPI}
+       * @param {Parameters<SetType>[0]} cfg
+       */
+      $setType (cfg) {
+        const {
+          type, baseValue, bringIntoFocus, avoidReport, specificSchema
+        } = cfg;
         if (schemaObjs && specificSchema) {
-          const idx = schemaObjs.map((obj) => {
-            return JSON.stringify(obj);
-          }).indexOf(JSON.stringify(specificSchema));
+          const idx = schemaObjs.findIndex((obj) => {
+            return deepEqual(obj, specificSchema);
+          });
           if (idx === -1) {
             this.value = type;
           } else {
@@ -181,16 +467,15 @@ export const buildTypeChoices = ({
         this.$addAndValidateEditUI({baseValue, bringIntoFocus, avoidReport});
       },
       /**
-       * @type {(info: {
-       *   type: string,
-       *   specificSchema?: import('zodex').SzType
-       * }) => void} cfg
+       * @this {TypeChoicesElementAPI}
+       * @param {Parameters<SetTypeNoEditUI>[0]} cfg
        */
-      $setTypeNoEditUI ({type, specificSchema}) {
+      $setTypeNoEditUI (cfg) {
+        const {type, specificSchema} = cfg;
         if (schemaObjs && specificSchema) {
-          const idx = schemaObjs.map((obj) => {
-            return JSON.stringify(obj);
-          }).indexOf(JSON.stringify(specificSchema));
+          const idx = schemaObjs.findIndex((obj) => {
+            return deepEqual(obj, specificSchema);
+          });
           this.selectedIndex = idx + 1;
         } else {
           this.value = type;
@@ -198,22 +483,32 @@ export const buildTypeChoices = ({
         this.$setStyles();
       },
 
-      /** @type {SetStyles} */
+      /**
+       * @this {TypeChoicesElementAPI}
+       * @type {SetStyles}
+       */
       $setStyles () {
         const {value: type} = this;
         this.dataset.type = type; // Used for styling
         let ancestorEl = this.parentElement;
+        if (!ancestorEl) {
+          return;
+        }
         if (ancestorEl.nodeName.toLowerCase() !== 'fieldset') {
           // Grandparent check added for optional items placeholder
-          ancestorEl = this.parentElement.parentElement;
+          ancestorEl = ancestorEl.parentElement;
         }
-        if (ancestorEl.nodeName.toLowerCase() === 'fieldset') {
+        if (ancestorEl?.nodeName.toLowerCase() === 'fieldset') {
           ancestorEl.dataset.type = type;
           DOM.filterChildElements(ancestorEl, 'legend').forEach((legend) => {
             legend.dataset.type = type;
           });
         }
       },
+      /**
+       * @this {TypeChoicesElementAPI}
+       * @type {GetTypeRoot}
+       */
       $getTypeRoot () {
         const container = this.$getContainer();
         /* istanbul ignore if -- How to replicate? */
@@ -223,11 +518,16 @@ export const buildTypeChoices = ({
         return $e(container, 'div[data-type]');
       },
 
-      /** @type {AddAndValidateEditUI} */
-      $addAndValidateEditUI (/* istanbul ignore next -- Backup */ {
-        baseValue, bringIntoFocus, schemaObject, avoidReport
-      /* istanbul ignore next -- Backup */
-      } = {}) {
+      /**
+       * @this {TypeChoicesElementAPI}
+       * @param {Parameters<AddAndValidateEditUI>[0]} [cfg]
+       */
+      $addAndValidateEditUI (
+        /* istanbul ignore next -- Backup */ cfg = {}
+      ) {
+        const {
+          baseValue, bringIntoFocus, schemaObject, avoidReport
+        } = cfg;
         const {value: type} = this;
 
         if (!type) {
@@ -242,7 +542,7 @@ export const buildTypeChoices = ({
         editUI = types.getUIForModeAndType({
           readonly: false,
           typeNamespace,
-          type,
+          type: /** @type {import('./types.js').AvailableArbitraryType} */ (type),
           bringIntoFocus,
           hasValue: type === 'arrayNonindexKeys' && baseValue,
           value: baseValue,
@@ -250,8 +550,10 @@ export const buildTypeChoices = ({
           format,
           topRoot,
           schemaContent: schemaOriginal ??
-            (schemaContent?.type === 'union' && schemaIdx !== undefined
-              ? schemaContent.options[schemaIdx]
+            (schemaIdx !== undefined && isUnionLike(schemaContent?.type)
+              ? /** @type {import('zodexy').SzUnion} */ (
+                schemaContent
+              ).options[schemaIdx]
               : schemaContent),
           // Added `schemaContent` as inner arrays were not getting their
           //   schema info; this apparently allows (actually requires)
@@ -263,11 +565,12 @@ export const buildTypeChoices = ({
             // Avoid JSON references by using this by default (or only?)
             (schemaObjs?.[sel.selectedIndex - 1]) ??
 
-            // eslint-disable-next-line @stylistic/max-len -- Long
             /* istanbul ignore next -- Can probably remove as `schemaObjs` will be set */
-            (schemaContent?.type === 'union' && schemaIdx !== undefined
+            (schemaIdx !== undefined && isUnionLike(schemaContent?.type)
               /* istanbul ignore next -- Can probably remove */
-              ? schemaContent.options[schemaIdx]
+              ? /** @type {import('zodexy').SzUnion} */ (
+                schemaContent
+              ).options[schemaIdx]
               // This is probably just `undefined` by here
               : schemaContent),
           schemaFallingBack: Boolean(!schemaObject && schemaContent)
@@ -281,15 +584,21 @@ export const buildTypeChoices = ({
         types.validateAllReferences({topRoot});
       },
 
-      /** @type {AddTypeAndEditUI} */
-      $addTypeAndEditUI ({type, editUI, specificSchema}) {
+      /**
+       * @this {TypeChoicesElementAPI}
+       * @param {Parameters<AddTypeAndEditUI>[0]} cfg
+       */
+      $addTypeAndEditUI (cfg) {
+        const {type, editUI, specificSchema} = cfg;
         this.$setTypeNoEditUI({type, specificSchema});
         this.$addEditUI({editUI});
       },
       /**
-       * @type {(info: {editUI: HTMLElement}) => void}
+       * @this {TypeChoicesElementAPI}
+       * @param {Parameters<AddEditUI>[0]} cfg
        */
-      $addEditUI ({editUI}) {
+      $addEditUI (cfg) {
+        const {editUI} = cfg;
         const container = this.$getContainer();
         DOM.removeChildren(container);
         jml(editUI, container);
@@ -297,22 +606,28 @@ export const buildTypeChoices = ({
       $getContainer () {
         return this.nextElementSibling;
       },
+      /**
+       * @this {TypeChoicesElementAPI}
+       */
       $getTopRoot () {
         return topRoot || this.$getTypeRoot();
       },
       /**
-       * @param {{avoidReport?: boolean}} cfg
-       * @returns {boolean}
+       * @this {TypeChoicesElementAPI}
+       * @param {Parameters<Validate>[0]} [cfg]
        */
-      $validate ({avoidReport} = {}) {
+      $validate (cfg = {}) {
+        const {avoidReport} = cfg;
         const {value: type} = this;
         const container = this.$getContainer();
         if (!container.firstElementChild) {
           return false;
         }
-        const editUI = container.firstElementChild;
+        const editUI = /** @type {HTMLDivElement} */ (container.firstElementChild);
         return types.validate({
-          type, root: editUI, topRoot: this.$getTopRoot(),
+          type: /** @type {import('./types.js').AvailableArbitraryType} */ (type),
+          root: editUI,
+          topRoot: this.$getTopRoot(),
           avoidReport
         });
       }
@@ -336,7 +651,6 @@ export const buildTypeChoices = ({
       '(Choose a type)'
     ]],
 
-    // @ts-expect-error Apparent TS bug
     ...typeOptions.map(
       ([optText, optAtts], idx) => {
         return [
@@ -350,13 +664,42 @@ export const buildTypeChoices = ({
       }
     )
   ]));
-  if (autoTrigger && typeOptions.length === 1 && !setValue) {
-    setTimeout(() => {
+
+  // `xor` (exclusive union): exactly one branch may match. Present it as a
+  //   labelled radio group ("choose exactly one of these") rather than the
+  //   flat type pull-down; the layout conveys the rule without the reader
+  //   needing to know the term. The element still exposes the
+  //   `<select>`-shaped surface (`value`, `selectedIndex`, `selectedOptions`,
+  //   the `$`-methods) that the rest of the type machinery reads.
+  const useXorTypeChoices = Boolean(
+    schemaObjs && !requireObject && typeOptions.length > 1 &&
+    (schemaContent?.type === 'xor' || schemaOriginal?.type === 'xor')
+  );
+
+  const sel = useXorTypeChoices
+    ? buildXorTypeChoices({
+      typeNamespace, keySelectClass, typeOptions, types, typeContainer,
+      schemaObjs: /** @type {import('zodexy').SzType[]} */ (schemaObjs),
+      xorSchema: /** @type {import('zodexy').SzUnion} */ (
+        schemaContent?.type === 'xor' ? schemaContent : schemaOriginal
+      ),
+      selectEl
+    })
+    : selectEl;
+
+  if (autoTrigger && !setValue && typeOptions.length === 1) {
+    setTimeout(async () => {
+      if (!await waitForConnection(sel)) {
+        return;
+      }
       sel.selectedIndex = 1;
       sel.dispatchEvent(new Event('change'));
-    });
+    }, 0);
   } else if (setValue || (requireObject && !objectHasValue)) {
     setTimeout(async () => {
+      if (!await waitForConnection(sel)) {
+        return;
+      }
       if (!setValue) { // if (requireObject && !objectHasValue) {
         // Todo (low): We could auto-populate keypath if has
         //   keypath (and we probably also only want if
@@ -384,11 +727,11 @@ export const buildTypeChoices = ({
           Types.getTypeForRoot(/** @type {HTMLDivElement} */ (
             rootEditUI
           ));
-        // eslint-disable-next-line @stylistic/max-len -- Long
         /** @type {HTMLSelectElement & {$addTypeAndEditUI: AddTypeAndEditUI}} */ (
           sel
         ).$addTypeAndEditUI({
-          type, editUI: rootEditUI,
+          type,
+          editUI: rootEditUI,
           // We do actually want the first one
           specificSchema: specificSchemas?.[0]
         });
@@ -401,11 +744,9 @@ export const buildTypeChoices = ({
         /* istanbul ignore next -- How to trigger? */
         console.log('err', err);
       }
-    });
+    }, 0);
   }
 
-  const typeContainer = jml('div', {class: 'typeContainer'});
-
   return {
     domArray: [
       sel,
@@ -425,9 +766,13 @@ export const buildTypeChoices = ({
 
     /** @type {ValidValuesSet} */
     validValuesSet () {
-      const root = /** @type {HTMLDivElement} */ (
+      const root = /** @type {HTMLDivElement|null} */ (
         $e(typeContainer, 'div[data-type]')
       );
+      if (!root) {
+        // No type/branch chosen yet: nothing valid has been set
+        return false;
+      }
       const form = /** @type {HTMLFormElement} */ (root.closest('form'));
       return Types.validValuesSet({form, typeNamespace});
     },