@lion/ui 0.25.0 → 0.26.0

package/components/form/test-suites/lion-form.suite.js

@@ -0,0 +1,398 @@
+import { html } from 'lit/static-html.js';
+import { LionField, Required } from '@lion/ui/form-core.js';
+import '@lion/ui/define/lion-validation-feedback.js';
+import { LionFieldset } from '@lion/ui/fieldset.js';
+import { LionCheckbox, LionCheckboxGroup } from '@lion/ui/checkbox-group.js';
+import '@lion/ui/define/lion-checkbox-group.js';
+import { LionRadio, LionRadioGroup } from '@lion/ui/radio-group.js';
+import '@lion/ui/define/lion-radio-group.js';
+import '@lion/ui/define/lion-fieldset.js';
+import '@lion/ui/define/lion-checkbox.js';
+import { LionListbox, LionOption } from '@lion/ui/listbox.js';
+import '@lion/ui/define/lion-listbox.js';
+import '@lion/ui/define/lion-option.js';
+import '@lion/ui/define/lion-field.js';
+import '@lion/ui/define/lion-radio.js';
+import { LionForm } from '@lion/ui/form.js';
+import '@lion/ui/define/lion-form.js';
+import { spy } from 'sinon';
+import {
+  fixture as _fixture,
+  unsafeStatic,
+  aTimeout,
+  defineCE,
+  oneEvent,
+  expect,
+} from '@open-wc/testing';
+import { resolveSuiteTag } from '../../core/test-helpers/resolveSuiteTag.js';
+import { isActiveElement } from '../../core/test-helpers/isActiveElement.js';
+
+/**
+ * @typedef {import('@lion/ui/types/test-suites.js').SuiteElement} SuiteElement
+ * Runs the `lion-form` behavioural suite, moved out of `test/lion-form.test.js` so a Subclasser can run
+ * the same guarantees against its own element. Pass `tagString` to point it at your registered
+ * tag; see docs/guides/principles/test-suites.md.
+ * `tagString`, `klass` and the older role tag keys are deprecated: pass `classes` instead (Lion
+ * itself uses `classes` everywhere).
+ * @param {import('@lion/ui/types/test-suites.js').SuiteConfig<{'checkbox-group': SuiteElement; 'radio-group': SuiteElement; checkbox: SuiteElement; fieldset: SuiteElement; host: SuiteElement; listbox: SuiteElement; option: SuiteElement; radio: SuiteElement}, {checkboxGroupTagString?: any; checkboxTagString?: any; fieldsetTagString?: any; listboxTagString?: any; optionTagString?: any; radioGroupTagString?: any; radioTagString?: any}>} [customConfig]
+ */
+export function runFormSuite({
+  classes: {
+    host: hostEl = LionForm,
+    'checkbox-group': roleCheckboxGroup = LionCheckboxGroup,
+    'radio-group': roleRadioGroup = LionRadioGroup,
+    fieldset: roleFieldset = LionFieldset,
+    checkbox: roleCheckbox = LionCheckbox,
+    listbox: roleListbox = LionListbox,
+    option: roleOption = LionOption,
+    radio: roleRadio = LionRadio,
+  } = {},
+  tagString: legacyTagString,
+  checkboxGroupTagString: legacyCheckboxGroupTagString,
+  radioGroupTagString: legacyRadioGroupTagString,
+  fieldsetTagString: legacyFieldsetTagString,
+  checkboxTagString: legacyCheckboxTagString,
+  listboxTagString: legacyListboxTagString,
+  optionTagString: legacyOptionTagString,
+  radioTagString: legacyRadioTagString,
+} = {}) {
+  const tag = unsafeStatic(resolveSuiteTag(hostEl, legacyTagString));
+  const tagNameCheckboxGroup = resolveSuiteTag(roleCheckboxGroup, legacyCheckboxGroupTagString);
+  const tagCheckboxGroup = unsafeStatic(tagNameCheckboxGroup);
+  const tagNameRadioGroup = resolveSuiteTag(roleRadioGroup, legacyRadioGroupTagString);
+  const tagRadioGroup = unsafeStatic(tagNameRadioGroup);
+  const tagNameFieldset = resolveSuiteTag(roleFieldset, legacyFieldsetTagString);
+  const tagFieldset = unsafeStatic(tagNameFieldset);
+  const tagNameCheckbox = resolveSuiteTag(roleCheckbox, legacyCheckboxTagString);
+  const tagCheckbox = unsafeStatic(tagNameCheckbox);
+  const tagNameListbox = resolveSuiteTag(roleListbox, legacyListboxTagString);
+  const tagListbox = unsafeStatic(tagNameListbox);
+  const tagNameOption = resolveSuiteTag(roleOption, legacyOptionTagString);
+  const tagOption = unsafeStatic(tagNameOption);
+  const tagNameRadio = resolveSuiteTag(roleRadio, legacyRadioTagString);
+  const tagRadio = unsafeStatic(tagNameRadio);
+
+  /**
+   * @typedef {import('lit').TemplateResult} TemplateResult
+   */
+  const fixture = /** @type {(arg: TemplateResult) => Promise<LionForm>} */ _fixture;
+  const childTagString = defineCE(
+    class extends LionField {
+      get slots() {
+        return {
+          input: () => document.createElement('input'),
+        };
+      }
+    },
+  );
+  const childTag = unsafeStatic(childTagString);
+  describe('<lion-form>', () => {
+    it('is an instance of LionFieldSet', async () => {
+      const el = await fixture(html`
+        <${tag}>
+          <form></form>
+        </${tag}>
+      `);
+      expect(el).to.be.instanceOf(LionFieldset);
+    });
+    it('relies on the native form for its accessible role', async () => {
+      const el = await fixture(html`
+        <${tag}>
+          <form></form>
+        </${tag}>
+      `);
+      expect(el.getAttribute('role')).to.be.null;
+    });
+    it('has a custom reset that gets triggered by native reset', async () => {
+      const withDefaults = await fixture(html`
+        <${tag}>
+          <form>
+            <${childTag} name="firstName" .modelValue="${'Foo'}"></${childTag}>
+            <input type="reset" value="reset-button" />
+          </form>
+        </${tag}>
+      `);
+      const resetButton =
+        /** @type {HTMLInputElement} */
+        withDefaults.querySelector('input[type=reset]');
+      withDefaults.formElements.firstName.modelValue = 'updatedFoo';
+      expect(withDefaults.modelValue).to.deep.equal({
+        firstName: 'updatedFoo',
+      });
+      withDefaults.reset();
+      expect(withDefaults.modelValue).to.deep.equal({
+        firstName: 'Foo',
+      });
+
+      // use button
+      withDefaults.formElements.firstName.modelValue = 'updatedFoo';
+      expect(withDefaults.modelValue).to.deep.equal({
+        firstName: 'updatedFoo',
+      });
+      resetButton.click();
+      expect(withDefaults.modelValue).to.deep.equal({
+        firstName: 'Foo',
+      });
+    });
+    it('dispatches reset events', async () => {
+      const el = await fixture(html`
+        <${tag}>
+          <form>
+            <${childTag} name="firstName" .modelValue="${'Foo'}"></${childTag}>
+          </form>
+        </${tag}>
+      `);
+      setTimeout(() => el.reset());
+      const resetEv = await oneEvent(el, 'reset');
+      expect(resetEv).to.be.instanceOf(Event);
+      expect(resetEv.type).to.equal('reset');
+      expect(resetEv.target).to.equal(el);
+      expect(resetEv.bubbles).to.be.true;
+      expect(resetEv.composed).to.be.false;
+    });
+    it('works with the native submit event (triggered via a button)', async () => {
+      const submitSpy = spy();
+      const el = await fixture(html`
+        <${tag} @submit=${submitSpy}>
+          <form>
+            <button type="submit">submit</button>
+          </form>
+        </${tag}>
+      `);
+      const button = /** @type {HTMLButtonElement} */ el.querySelector('button');
+      button.click();
+      expect(submitSpy.callCount).to.equal(1);
+    });
+    it('dispatches submit events', async () => {
+      const el = await fixture(html`
+        <${tag}>
+          <form>
+            <button type="submit">submit</button>
+          </form>
+        </${tag}>
+      `);
+      const button = /** @type {HTMLButtonElement} */ el.querySelector('button');
+      setTimeout(() => button.click());
+      const submitEv = await oneEvent(el, 'submit');
+      expect(submitEv).to.be.instanceOf(Event);
+      expect(submitEv.type).to.equal('submit');
+      expect(submitEv.target).to.equal(el);
+      expect(submitEv.bubbles).to.be.true;
+      expect(submitEv.composed).to.be.false;
+    });
+    it('redispatches a submit event on the native form node when calling submit() imperatively', async () => {
+      const nativeFormSubmitEventSpy = spy();
+      const el = await fixture(html`
+        <${tag}>
+          <form @submit=${nativeFormSubmitEventSpy}>
+            <button type="submit">submit</button>
+          </form>
+        </${tag}>
+      `);
+      const submitSpy = spy(el, 'submit');
+      const submitGroupSpy = spy(el, 'submitGroup');
+      el.submit();
+      expect(submitSpy.calledOnce).to.be.true;
+      expect(nativeFormSubmitEventSpy.calledOnce).to.be.true;
+      expect(submitGroupSpy.calledOnce).to.be.true;
+    });
+    it('handles internal submit handler before dispatch', async () => {
+      const el = await fixture(html`
+        <${tag}>
+          <form>
+            <button type="submit">submit</button>
+          </form>
+        </${tag}>
+      `);
+      const button = /** @type {HTMLButtonElement} */ el.querySelector('button');
+      const internalHandlerSpy = spy(el, 'submitGroup');
+      const dispatchSpy = spy(el, 'dispatchEvent');
+      await aTimeout(0);
+      button.click();
+      expect(internalHandlerSpy).to.be.calledBefore(dispatchSpy);
+    });
+    it('handles internal submit handler before dispatch', async () => {
+      const el = await fixture(html`
+        <${tag}>
+          <form>
+            <button type="submit">submit</button>
+          </form>
+        </${tag}>
+      `);
+      const button = /** @type {HTMLButtonElement} */ el.querySelector('button');
+      const internalHandlerSpy = spy(el, 'submitGroup');
+      const dispatchSpy = spy(el, 'dispatchEvent');
+      button.click();
+      expect(dispatchSpy.args[0][0].type).to.equal('submit');
+      expect(internalHandlerSpy).to.be.calledBefore(dispatchSpy);
+    });
+    it('handles internal reset handler before dispatch', async () => {
+      const el = await fixture(html`
+        <${tag}>
+          <form>
+            <button type="reset">reset</button>
+          </form>
+        </${tag}>
+      `);
+      const button = /** @type {HTMLButtonElement} */ el.querySelector('button');
+      const internalHandlerSpy = spy(el, 'resetGroup');
+      const dispatchSpy = spy(el, 'dispatchEvent');
+      button.click();
+      expect(dispatchSpy.args[0][0].type).to.equal('reset');
+      expect(internalHandlerSpy).to.be.calledBefore(dispatchSpy);
+    });
+    it('sets focus on submit to the first erroneous form element', async () => {
+      const el = await fixture(html`
+        <${tag}>
+          <form>
+            <${childTag} name="firstName" .modelValue=${'Foo'} .validators=${[new Required()]}></${childTag}>
+            <${childTag} name="lastName" .validators=${[new Required()]}></${childTag}>
+            <button type="submit">submit</button>
+          </form>
+        </${tag}>
+      `);
+      expect(el.getAttribute('aria-invalid')).to.equal('false');
+      const button = /** @type {HTMLButtonElement} */ el.querySelector('button');
+      const dispatchSpy = spy(el, 'dispatchEvent');
+      button.click();
+      expect(dispatchSpy.args.map((args) => args[0].type)).to.contain('submit');
+      // @ts-ignore [allow-protected] in test
+      expect(isActiveElement(el.formElements[1]._inputNode)).to.be.true;
+    });
+    it('sets focus on submit to the first erroneous form element within a fieldset', async () => {
+      const el = await fixture(html`
+        <${tag}>
+          <form>
+            <${tagFieldset} name="name">
+              <${childTag} name="firstName" .modelValue=${'Foo'} .validators=${[new Required()]}></${childTag}>
+              <${childTag} name="lastName" .validators=${[new Required()]}></${childTag}>
+            </${tagFieldset}>
+            <button type="submit">submit</button>
+          </form>
+        </${tag}>
+      `);
+      const button = /** @type {HTMLButtonElement} */ el.querySelector('button');
+      const dispatchSpy = spy(el, 'dispatchEvent');
+      button.click();
+      expect(dispatchSpy.args.map((args) => args[0].type)).to.contain('submit');
+      const fieldset = el.formElements[0];
+      // @ts-ignore [allow-protected] in test
+      expect(isActiveElement(fieldset.formElements[1]._inputNode)).to.be.true;
+    });
+    it('sets focus on submit to the first form element within a erroneous fieldset', async () => {
+      const el = await fixture(html`
+        <${tag}>
+          <form>
+            <${tagFieldset} name="name" .validators=${[new Required()]}>
+              <${childTag} name="firstName"></${childTag}>
+              <${childTag} name="lastName"></${childTag}>
+            </${tagFieldset}>
+            <button type="submit">submit</button>
+          </form>
+        </${tag}>
+      `);
+      const button = /** @type {HTMLButtonElement} */ el.querySelector('button');
+      const dispatchSpy = spy(el, 'dispatchEvent');
+      button.click();
+      expect(dispatchSpy.args.map((args) => args[0].type)).to.contain('submit');
+      const fieldset = el.formElements[0];
+      expect(isActiveElement(fieldset.formElements[0]._inputNode)).to.be.true;
+    });
+    it('sets focus on submit to the first form element within a erroneous fieldset within another fieldset', async () => {
+      const el = await fixture(html`
+        <${tag}>
+          <form>
+            <${tagFieldset} name="parentFieldset">
+              <${tagFieldset} name="childFieldset" .validators="${[new Required()]}">
+                <${childTag} name="firstName"></${childTag}>
+              </${tagFieldset}>
+            </${tagFieldset}>
+
+            <button type="submit">submit</button>
+          </form>
+        </${tag}>
+      `);
+      const button = /** @type {HTMLButtonElement} */ el.querySelector('button');
+      const parentFieldSetEl = el.formElements[0];
+      const childFieldsetEl = parentFieldSetEl.formElements[0];
+      const inputEl = childFieldsetEl.formElements[0];
+      button.click();
+      expect(isActiveElement(inputEl._focusableNode)).to.be.true;
+    });
+    it('sets focus on submit to the first form element within a erroneous listbox', async () => {
+      const el = await fixture(html`
+        <${tag}>
+          <form>
+            <${tagListbox} name="name" .validators="${[new Required()]}">
+              <${tagOption} value="a">a</${tagOption}>
+              <${tagOption} value="b">b</${tagOption}>
+            </${tagListbox}>
+            <button type="submit">submit</button>
+          </form>
+        </${tag}>
+      `);
+      const button = /** @type {HTMLButtonElement} */ el.querySelector('button');
+      button.click();
+      const listboxEl = el.formElements[0];
+      expect(isActiveElement(listboxEl._inputNode)).to.be.true;
+    });
+    it('sets focus on submit to the first form element within a erroneous listbox within a fieldset', async () => {
+      const el = await fixture(html`
+        <${tag}>
+          <form>
+            <${tagFieldset} name="fieldset">
+              <${tagListbox} name="name" .validators="${[new Required()]}">
+                <${tagOption} value="a">a</${tagOption}>
+                <${tagOption} value="b">b</${tagOption}>
+              </${tagListbox}>
+            </${tagFieldset}>
+            <button type="submit">submit</button>
+          </form>
+        </${tag}>
+      `);
+      const button = /** @type {HTMLButtonElement} */ el.querySelector('button');
+      button.click();
+      const fieldsetEl = el.formElements[0];
+      const listboxEl = fieldsetEl.formElements[0];
+      expect(isActiveElement(listboxEl._inputNode)).to.be.true;
+    });
+    it('sets focus on submit to the first form element within a erroneous checkbox-group', async () => {
+      const el = await fixture(html`
+        <${tag}>
+          <form>
+            <${tagCheckboxGroup} name="name" .validators="${[new Required()]}">
+              <${tagCheckbox} .choiceValue=${'a'} label="a"></${tagCheckbox}>
+              <${tagCheckbox} .choiceValue=${'b'} label="b"></${tagCheckbox}>
+            </${tagCheckboxGroup}>
+            <button type="submit">submit</button>
+          </form>
+        </${tag}>
+      `);
+      const button = /** @type {HTMLButtonElement} */ el.querySelector('button');
+      const checkboxGroupEl = el.formElements[0];
+      const checkboxEl = checkboxGroupEl.formElements[0];
+      button.click();
+      expect(isActiveElement(checkboxEl._focusableNode)).to.be.true;
+    });
+    it('sets focus on submit to the first form element within a erroneous radio-group', async () => {
+      const el = await fixture(html`
+        <${tag}>
+          <form>
+              <${tagRadioGroup} name="name" .validators="${[new Required()]}">
+                <${tagRadio} .choiceValue=${'a'} label="a"></${tagRadio}>
+                <${tagRadio} .choiceValue=${'b'} label="b"></${tagRadio}>
+              </${tagRadioGroup}>
+            </${tagFieldset}>
+
+            <button type="submit">submit</button>
+          </form>
+        </${tag}>
+      `);
+      const button = /** @type {HTMLButtonElement} */ el.querySelector('button');
+      const radioGroupEl = el.formElements[0];
+      const radioEl = radioGroupEl.formElements[0];
+      button.click();
+      expect(isActiveElement(radioEl._focusableNode)).to.be.true;
+    });
+  });
+}

package/components/form-core/test/FormatMixin.test.js

@@ -1,5 +1,8 @@
+import { LionInput } from '@lion/ui/input.js';
 import { runFormatMixinSuite } from '../test-suites/FormatMixin.suite.js';
 runFormatMixinSuite({
-  tagString: null,
+  classes: {
+    host: LionInput,
+  },
   modelValueType: String,
 });

package/components/form-core/test/choice-group/CustomChoiceGroupMixin.integrations.test.js

@@ -38,16 +38,29 @@ customElements.define(
   MultipleCustomChoiceGroupAllowCustom,
 );
 runChoiceGroupMixinSuite({
+  classes: {
+    host: CustomChoiceGroup,
+  },
+  // synthetic tag: not derivable from the class name, so the deprecated key names the element
   parentTagString: 'custom-choice-input-group',
 });
 runChoiceGroupMixinSuite({
+  classes: {
+    host: MultipleCustomChoiceGroup,
+  },
   parentTagString: 'multiple-custom-choice-input-group',
   choiceType: 'multiple',
 });
 runChoiceGroupMixinSuite({
+  classes: {
+    host: CustomChoiceGroupAllowCustom,
+  },
   parentTagString: 'allow-custom-choice-input-group',
 });
 runChoiceGroupMixinSuite({
+  classes: {
+    host: MultipleCustomChoiceGroupAllowCustom,
+  },
   parentTagString: 'multiple-allow-custom-choice-input-group',
   choiceType: 'multiple',
 });

package/components/form-core/test-suites/FormRegistrationMixins.suite.js

@@ -7,35 +7,30 @@ import {
 import { defineCE, expect, fixture, html, unsafeStatic } from '@open-wc/testing';
 import { LitElement } from 'lit';
 import sinon from 'sinon';
+import { resolveSuiteTag } from '../../core/test-helpers/resolveSuiteTag.js';
 
 /**
- * @typedef {Object} customConfig
- * @property {typeof LitElement|undefined} [baseElement]
- * @property {string} [customConfig.suffix]
- * @property {string} [customConfig.parentTagString]
- * @property {string} [customConfig.childTagString]
- * @property {string} [customConfig.portalTagString]
+ * Runs the form-registration suite. The caller hands the three elements it should run against -
+ * `host` is the registrar (the form), `child` what registers itself and `portal` the element that
+ * forwards registrations; anything left out keeps the class this suite builds from the mixins.
+ * @typedef {import('@lion/ui/types/test-suites.js').SuiteElement} SuiteElement
+ * @param {import('@lion/ui/types/test-suites.js').SuiteConfig<{host: SuiteElement; child: SuiteElement; portal: SuiteElement}, {suffix?: string, baseElement?: typeof LitElement}>} customConfig
  */
-
-/**
- * @param {customConfig} customConfig
- */
-export const runRegistrationSuite = (customConfig) => {
-  const cfg = {
-    baseElement: LitElement,
-    ...customConfig,
-  };
-  describe(`FormRegistrationMixins ${cfg.suffix}`, () => {
-    class RegistrarClass extends FormRegistrarMixin(cfg.baseElement) {}
-    cfg.parentTagString = defineCE(RegistrarClass);
-    class RegisteringClass extends FormRegisteringMixin(cfg.baseElement) {}
-    cfg.childTagString = defineCE(RegisteringClass);
-    class PortalClass extends FormRegistrarPortalMixin(cfg.baseElement) {}
-    cfg.portalTagString = defineCE(PortalClass);
-    const parentTag = unsafeStatic(cfg.parentTagString);
-    const childTag = unsafeStatic(cfg.childTagString);
-    const portalTag = unsafeStatic(cfg.portalTagString);
-    const { parentTagString, childTagString } = cfg;
+export const runRegistrationSuite = ({
+  classes = {},
+  suffix = '',
+  baseElement = LitElement,
+} = {}) => {
+  describe(`FormRegistrationMixins ${suffix}`, () => {
+    class RegistrarClass extends FormRegistrarMixin(baseElement) {}
+    const parentTagString = resolveSuiteTag(classes?.host, undefined, RegistrarClass);
+    class RegisteringClass extends FormRegisteringMixin(baseElement) {}
+    const childTagString = resolveSuiteTag(classes?.child, undefined, RegisteringClass);
+    class PortalClass extends FormRegistrarPortalMixin(baseElement) {}
+    const portalTagString = resolveSuiteTag(classes?.portal, undefined, PortalClass);
+    const parentTag = unsafeStatic(parentTagString);
+    const childTag = unsafeStatic(childTagString);
+    const portalTag = unsafeStatic(portalTagString);
     it('can register a formElement', async () => {
       const el =
         /** @type {RegistrarClass} */

package/components/form-core/test-suites/FormatMixin.suite.js

@@ -4,6 +4,7 @@ import { parseDate } from '@lion/ui/localize-no-side-effects.js';
 import { aTimeout, defineCE, expect, fixture, html, unsafeStatic } from '@open-wc/testing';
 import { LitElement } from 'lit';
 import sinon from 'sinon';
+import { resolveSuiteTag } from '../../core/test-helpers/resolveSuiteTag.js';
 const isLionInputStepper = (/** @type {FormatClass} */ el) => 'valueTextMapping' in el;
 
 /**
@@ -31,20 +32,6 @@ class FormatClass extends FormatMixin(LitElement) {
   }
 }
 
-/**
- * @typedef {object} FormatMixinSuiteConfig
- * @property {string | null} [tagString] - Optional. Element tag name; if omitted, one will be auto-generated via defineCE()
- * @property {string | null} [childTagString] - Optional. Not currently used
- * @property {ArrayConstructor | ObjectConstructor | NumberConstructor | BooleanConstructor | StringConstructor | DateConstructor | 'iban' | 'email'} modelValueType - REQUIRED. The model value type for this component
- * @property {(opts: { toggleValue: boolean, viewValue: boolean }) => any} [valueToggler] - Optional. Provide different test values for toggleValue=false vs toggleValue=true. If not provided, defaults will be generated based on modelValueType.
- * @property {(el: FormatClass) => any} [getExpectedInitialModelValue] - Optional. Expected initial modelValue state when element is created without a value. If not provided, defaults will be generated based on modelValueType.
- * @property {(el: FormatClass) => any} [getExpectedInitialFormattedValue] - Optional. Expected initial formattedValue state when element is created without a value. If not provided, defaults will be generated based on modelValueType.
- * @property {(el: FormatClass) => any} [getExpectedInitialSerializedValue] - Optional. Expected initial serializedValue state when element is created without a value. If not provided, defaults will be generated based on modelValueType.
- * @property {(el: FormatClass) => any} [getExpectedModelValueForEmptyInputNode] - Optional. Expected modelValue after user clears the input node value. Defaults to empty string.
- * @property {(value: string, opts?: any) => any} [parser] - Optional. Parser override used by tests. When provided, it is applied before connectedCallback so fallback init sync uses it.
- * @property {number} [valueChangeCounterOffset] - Optional. Offset for model-value-changed event counter. Use 0 for most types, 1 for Date types where parseDate() creates new objects. If not provided, defaults will be generated based on modelValueType.
- */
-
 /**
  * Creates default valueToggler based on modelValueType for backwards compatibility
  * @param {ArrayConstructor | ObjectConstructor | NumberConstructor | BooleanConstructor | StringConstructor | DateConstructor | 'iban' | 'email'} modelValueType
@@ -157,41 +144,59 @@ function createDefaultValueChangeCounterOffset(modelValueType) {
   return 0;
 }
 
+/** @typedef {import('@lion/ui/types/test-suites.js').SuiteElement} SuiteElement */
+
 /**
- * @param {FormatMixinSuiteConfig} [customConfig]
+ * Runs the `FormatMixin` behavioural suite. The caller hands the element to run against (leaving
+ * `host` out keeps the element this suite builds from the mixin) and says what the model value type
+ * is; the expectations that follow from that type are generated, and every one of them can be
+ * overridden.
+ * @param {import('@lion/ui/types/test-suites.js').SuiteConfig<{host: SuiteElement}, {
+ *   modelValueType: ArrayConstructor | ObjectConstructor | NumberConstructor | BooleanConstructor | StringConstructor | DateConstructor | 'iban' | 'email',
+ *   valueToggler?: (opts: { toggleValue: boolean, viewValue: boolean }) => any,
+ *   getExpectedInitialModelValue?: (el: FormatClass) => any,
+ *   getExpectedInitialFormattedValue?: (el: FormatClass) => any,
+ *   getExpectedInitialSerializedValue?: (el: FormatClass) => any,
+ *   getExpectedModelValueForEmptyInputNode?: (el: FormatClass) => any,
+ *   parser?: (value: string, opts?: any) => any,
+ *   valueChangeCounterOffset?: number,
+ * }>} [customConfig]
  */
-export function runFormatMixinSuite(customConfig) {
-  const cfg = {
-    ...customConfig,
-  };
-
-  // Validate that modelValueType is provided (required for generating defaults)
-  if (!cfg.modelValueType) {
+export function runFormatMixinSuite({
+  classes = {},
+  tagString: legacyTagString,
+  modelValueType,
+  valueToggler: customValueToggler,
+  getExpectedInitialModelValue: customGetExpectedInitialModelValue,
+  getExpectedInitialFormattedValue: customGetExpectedInitialFormattedValue,
+  getExpectedInitialSerializedValue: customGetExpectedInitialSerializedValue,
+  getExpectedModelValueForEmptyInputNode: customGetExpectedModelValueForEmptyInputNode,
+  parser: customParser,
+  valueChangeCounterOffset: customValueChangeCounterOffset,
+} = {}) {
+  if (!modelValueType) {
     throw new Error(
       'FormatMixinSuite: modelValueType is REQUIRED in config. ' +
         'Provide the model value type for this component (e.g., String, Number, Date, Object, Boolean, Array, "iban", "email").',
     );
   }
-
-  // Use provided values or generate defaults based on modelValueType
-  const valueToggler = cfg.valueToggler || createDefaultValueToggler(cfg.modelValueType);
+  const valueToggler = customValueToggler || createDefaultValueToggler(modelValueType);
   const getExpectedInitialModelValue =
-    cfg.getExpectedInitialModelValue ||
-    createDefaultGetExpectedInitialModelValue(cfg.modelValueType);
+    customGetExpectedInitialModelValue || createDefaultGetExpectedInitialModelValue(modelValueType);
   const getExpectedInitialFormattedValue =
-    cfg.getExpectedInitialFormattedValue ||
-    createDefaultGetExpectedInitialFormattedValue(cfg.modelValueType);
+    customGetExpectedInitialFormattedValue ||
+    createDefaultGetExpectedInitialFormattedValue(modelValueType);
   const getExpectedInitialSerializedValue =
-    cfg.getExpectedInitialSerializedValue ||
-    createDefaultGetExpectedInitialSerializedValue(cfg.modelValueType);
+    customGetExpectedInitialSerializedValue ||
+    createDefaultGetExpectedInitialSerializedValue(modelValueType);
   const getExpectedModelValueForEmptyInputNode =
-    cfg.getExpectedModelValueForEmptyInputNode || (() => '');
+    customGetExpectedModelValueForEmptyInputNode || (() => '');
   const defaultParser = (/** @type {string} */ value) => value.replace('foo: ', '');
-  const parser = cfg.parser || defaultParser;
+  const parser = customParser || defaultParser;
   const valueChangeCounterOffset =
-    cfg.valueChangeCounterOffset !== undefined
-      ? cfg.valueChangeCounterOffset
-      : createDefaultValueChangeCounterOffset(cfg.modelValueType);
+    customValueChangeCounterOffset !== undefined
+      ? customValueChangeCounterOffset
+      : createDefaultValueChangeCounterOffset(modelValueType);
 
   /**
    * Generates test values by delegating to the component's valueToggler function.
@@ -258,10 +263,7 @@ export function runFormatMixinSuite(customConfig) {
     /** @type {FormatClass} */
     let fooFormat;
     before(async () => {
-      if (!cfg.tagString) {
-        cfg.tagString = defineCE(FormatClass);
-      }
-      tag = unsafeStatic(cfg.tagString);
+      tag = unsafeStatic(resolveSuiteTag(classes?.host, legacyTagString, FormatClass));
       fooFormat = await fixture(html`
         <${tag}
           .formatter="${/** @param {string} value */ (value) => `foo: ${value}`}"
@@ -570,7 +572,7 @@ export function runFormatMixinSuite(customConfig) {
       });
       describe('Formatter', () => {
         it('only calls the formatter for valid values on `user-input-changed` ', async () => {
-          if (cfg.modelValueType === Object) {
+          if (modelValueType === Object) {
             return;
           }
           const formatterSpy = sinon.spy((value) => `foo: ${value}`);
@@ -817,7 +819,7 @@ export function runFormatMixinSuite(customConfig) {
           expect(_inputNode.value).to.equal(val);
         });
         it('does only calculate derived values as consequence of user input when preprocessed value is different from previous view value', async () => {
-          if (cfg.modelValueType === Object) return;
+          if (modelValueType === Object) return;
           const val =
             generateValueBasedOnType({
               viewValue: true,
@@ -904,7 +906,7 @@ export function runFormatMixinSuite(customConfig) {
           it('updates return viewValue and caretIndex', async () => {
             /**
              * @param {string} viewValue
-             * @param {{ prevViewValue: string; currentCaretIndex: number; }} meta
+             * @param {{ classes?: Record<string, CustomElementConstructor>, prevViewValue: string; currentCaretIndex: number; }} meta
              */
             function myPreprocessor(viewValue, { currentCaretIndex }) {
               return {