Form-associated mixins/controllers

[calebdwilliams]

Would Open-WC be interested in publishing a set of utilities designed to help ease integrations with the ElementInternals spec to build form-associated custom elements? I have some ideas here that I've worked with @michaelwarren1106 on in the past. We're interested in making some of those concepts open source, but want don't really know of a great platform for this. Some core ideas:

• A FormControlMixin that takes a super class (probably LitElement, but potentially more generic) that has simple utilities or get/set patterns for setting the form-associated element's value and validity state based on a built-in element like HTMLInputElement, HTMLSelectElement, etc.
• A form associated mixin that doesn't necessarily forward the behavior/validity of a built-in control but that creates simple reactive validity/value bindings.
• A series of Lit controllers that will allow a user to easily compose form-associated behaviors, an example of this might be something like the following

import { ReactiveController, ReactiveControllerHost } from 'lit';
import { IElementInternals } from 'element-internals-polyfill';

export interface ValueControllerHost extends ReactiveControllerHost {
  value: string|FormData;
}

export class ValueController implements ReactiveController {
  host: ValueControllerHost;

  private internals: IElementInternals;
  private valueKey: string;

  constructor(host: ValueControllerHost, internals: IElementInternals, valueKey = 'value') {
    (this.host = host).addController(this);
    this.internals = internals;
    this.valueKey = valueKey;
  }

  private setValue(value: string|FormData): void {
    this.internals.setFormValue(value);
  }

  public reset(): void {
    this.internals.setFormValue('');
    this.host[this.valueKey] = '';
  }

  hostConnected() {
    this.setValue(this.value);
  }

  hostUpdated() {
    this.setValue(this.value);
  }

  get value() {
    return this.host[this.valueKey];
  }
}

If this isn't something open-wc is interested in supporting, I completely get that, but would be really interested in working with this group to begin filling this gap in the dev community.

[michaelwarren1106]

I second this kind of thing. I think that the UI world has long needed some sort of "standard library" for stuff like this, because every time we make a form element component, we end up re-writing these kinds of logic controllers different ways. IMO, the Lit ecosystem makes perfect sense to publish "the Lit version" of a lib that could aim to be a JS UI standard lib so that we dont have to re-invent the form controller wheel every time.

I've also got some other ideas for similar things, but on the "build tools" side of the house for folks that want to make icon components from a pile of SVGs, or turn a .scss/.css file into a compiled Typescript .css.ts file that exports css as a string in prep for Lit static styles importing, etc.

Id love for open-wc to be the home for these kinds of efforts instead of caleb and I working on spinning up another standalone UI library

[Westbrook]

I rather like the idea here!

Questions:

1. Is this an offering you're looking for partnership around developing or something you've mostly worked through an would like a home for?
2. Is this something that you'd be interested/willing to commit time to long term to ensure that it continues to support users as these APIs settle and begin to ship in more browsers?
3. Would you be able to give a high-level breakdown as to a list mixins/controllers you'd think would belong in such an offering?
4. I'd love to keep this discussion to "form-associated" constructs, but would it be possible to structure conversations around other offerings in a separate Discussion thread?

[Westbrook]

Another question:

• If these end up being lit-centric, would they more properly belong in @lit-labs? Or do you see a path to keeping these more web component-general?

[calebdwilliams]

Honestly regarding your final question I'm not sure. I'm open to any and all suggestions here. What I do know is that there's a gap here that can be filled and I'm interested in helping to fill it, but I'm not quite sure if this should just be a personal project or if there's interest from Open-WC or @lit-labs to partner in it. If no one wants it, I'm sure Michael and I will publish it ourselves, just wanting to engage a bit with the community and y'all as thought leaders around it first.

[michaelwarren1106]

@Westbrook my two cents on your questions:

1. I think some of the mixin/controller stuff has been thought through, but with LIt 1 as mixins, and not necessaarily with lit 2 as controllers, so I would be up for some partnership, especially if it means getting a really clean dev experience for stuff we do a lot.
2. i would be willing to commit to supporting it long term as work/family life permit, sure! I dig the open-wc community and its efforts, and have benefited from using lots of the OSS stuff in the open-wc, so i would love to give back as well.
3. Caleb mostly has the mixins/controllers list stuff. The things I have would be:
   • preventable events pattern helper functions : enables a component to be both stateful and stateless if desired
   • scoped elements pre-install script and loaders (could do webpack and rollup to start) for folks that need multiple versions of the same component on the same page at the same time and want to automate web comp tag name scoping
   • build script for processing .scss/.css files into importable .css.ts files so that Lit component devs can write css in external files and import styles into static styles
   • internal event helper functions to create/listen for events between components that shouldnt bubble/escape outside for component consumers to listen to
4. I can start up separate discussions for my stuff above.

[calebdwilliams]

I think Michael summed it up pretty well.

1. I do have some existing functionality already thought through and working, but it could definitely use some refinement. What I do know is that this is a gap that needs to be filled. To answer your question about true agnosticism of the approach, the current examples I have are built using Lit, but the concepts hold. The questions would be how best to translate those so they could work with Lit and HTMLElement components. Ultimately the idea is to create a decent wrapper around ElementInternals.
2. Yeah, I can commit to helping out for sure, but like Michael said family always comes first.
3. I think what I said earlier holds, there could be the following options:

Forward behavior

A FormControlMixin that defines APIs around common control behavior like validations (custom validations, required, disabled, value association, etc.). This mixin may or may not try to forward an internal control's behavior. Imagine the following:

class DesignSystemInput extends FormControl(LitElement) {
  static styles = css`/* styles */`;

  @property({ type: String, reflect: true })
  label = '';

  @query('input')
  input: HTMLInputElement;

  firstUpdated() {
    this.forwardControl(this.input);
  }

  render() {
    return html`<label for="input">${this.label}</label>
    <input id="input" name="${this.name}" ?required="${live(this.required)}" ?disabled="${live(this.disabled}" @input="${this.onInput}">`;
  }

  private onInput(event: KeyboardEvent) {
    this.value = (event.target as HTMLInputElement).value;
  }
}

In the above we could ostensibly forward the value and full validity state from DesignSystemInput.prototype.input to the element host. The returned type from FormControl has a set of existing assumptions like a disabled and required state and a value. The setter for value could call this.internals.setFormValue for the consumer (or we could alias this behavior to FormControl.prototype.formValue so we can support components like radios which need a checked state).

We know from experience that these things are likely to be common patterns that will need to be implemented repeatedly.

I suppose the linking function could fall to a directive, but I don't have a ton of experience in that space, so I can't speak to it well.

Composition

We could also potentially compose these behaviors by using a series of controllers like the ValueController above or a RequiredController and a CustomErrorController that manage validation state and error messages (think HTMLInputElement.prototype.validationMessage). The above mixin could even be a self composition of a series of controllers (especially if it is Lit-centric).

function FormControl(SuperClass) {
  return class extends SuperClass {
    static formAssociated = true;
    internals = this.attachInternals();

    valueController = new ValueController(this, this.internals);
    requiredController = new RequiredController(this, this.internals, 'valueKeyToEvaluate');
    /** etc. this is a naive example, hopefully the idea stands */
  }
}

[Westbrook]

This all sounds pretty exciting. With a focus on these form association controllers, how should we get started?

Should we start marking out APIs as a whole?
Do they make sense to break down into issues and discuss individually?
Do you have enough of a POC from previous work to start with a draft PR to review?

[calebdwilliams]

@Westbrook does that resonate a bit more? I think the success criteria should be:

• generic value setting features (including toggle support for cases like radio and/or checkbox-like behavior)
• proxying built-in validation schemes
• enabling custom validation
• enabling the setting of custom validation messages associated with built-in and custom validations
• implicit form submission API behavior (for instance on hitting Enter)
• the ability to respond to common state changes like going from disabled to enabled
• perhaps emitters for input/change type-events
• perhaps a property for when to show errors (based on industry best-practices)

[Westbrook]

I like this list. Do you count this list as a single mixin? One mixin for each of these bullets? A couple of mixins batching together some of these bullets each?

Is there one mixin that would be a good target to practice the process with?

[calebdwilliams]

My gut tells me this is a single mixin if we believe the API can be generic enough (I believe it can). I think my biggest question is if Open WC is interested in this would you prefer it to be Lit-specific or completely vanilla? Both are possible, but obviously one is much more complicated.

The following is kind of a concept for an overall API with a custom validation.

import { FormControlMixin } from 'wherever';

class ControlOne extends FormControlMixin(HTMLElement) {
  static formControlConfig = {
    valueProp: 'value'
  }

  connectedCallback() {
    super.connectedCallback();
    const root = this.attachShadow({ mode: 'open' });
    const input = document.createElement('input');
    root.append(input);
    input.addEventListener('input', this.onInput);
  }

  disconnectedCallback(): void {
    this.input.removeEventListener('input', this.onInput);
  }

  get input(): HTMLInputElement {
    return this.shadowRoot.querySelector('input');
  }

  private onInput = (event: Event): void => {
    this.value = (event.target as HTMLInputElement).value;
  } 

  formValueChangedCallback(value: string): void {
    if (value === 'foo') {
      this.queueValidity('Value cannot equal foo');
    }
  }
}

We could either bake in the common validators or add them as an argument to the static method:

import { FormControlMixin, requiredValidator } from 'wherever';

interface ValidationObject {
  key: string,
  message?: string,
  valid: boolean
}

function customValidator(value: string): ValidationObject {
  if (value === 'foo') {
    return { key: 'noFoo', message: 'Value cannot equal foo', valid: false };
  }
  return { key: 'noFoo', valid: true };
}

class ControlTwo extends FormControlMixin(HTMLElement) {
  static formControlConfig = {
    valueProp: 'value',
    validators: [requiredValidator, customValidator]
  };

  /** etc */
}

I personally lean toward the former, but that might be too much magic for some. Welcome to suggestions. All APIs are bikeshedable, I would love other input or I could develop both and see which one this community prefers.

[michaelwarren1106]

imo this is custom validation from the outside of the mixin, but still from the inside of the outer component. would there still be an error= or error-message= attr/prop for enabling custom validation message/validation state to come in from outside the web component?

[calebdwilliams]

@michaelwarren1106 So I have an implementation now that would allow for that programmatically. There might be a more elegant solution, it's something I'm thinking about. You can see an example of what I'm talking about in this file, specifically lines 56 – 58 which references back to a standardized validator definition.

If we used this pattern, what you described could potentially be

import { LitElement, html } from 'lit';
import { property, query } from 'lit/decorators.js';
import { FormControlMixin, Validator } from 'wherever';

export interface ProgramaticValidatorHost extends HTMLElement {
  error: string;
}

export const programaticValidator: Validator = {
  attribute: 'error',
  message: 'Default error message; instance can override',
  callback(instance: ProgramaticValidatorHost, value: any): boolean {
    return !!instance.error;
  }
};

class NaiveExample extends FormControlMixin(LitElement) {
  static get formControlValidators() {
    return [programaticValidator];
  }

  @property({ type: String, reflect: true })
  error = null;

  @property({ type: String })
  value = '';

  @query('input')
  validationTarget: HTMLInputElement;

  validationCallback(validationKey: string): string {
    if (validationKey === 'customError') {
      return this.error;
    }
  }

  render() {
    return html`<input @input="${this.#onInput}">`;
  }

  #onInput(event) {
    this.value = (event.target as HTMLInputElement).value;
  }
}

This is a more abstracted version of what we have worked on together in the past (which might be more appropriate for contexts outside the ones we had been working in). It's still not fully baked, but I think it has potential. Again, I'd welcome feedback on the shape of this thing.

[calebdwilliams]

OK, I've been playing with this quite a bit lately and I have a proof of concept ready that I'd love feedback on if you have a chance. This also includes a link to a demo on CodePen.

Limitations

• It's still a bit wonky on mobile Safari, but as this is just a POC, it's fine.
• Since the ElementInternals polyfill doesn't include a native popup for validation, browsers other than Chrome won't display a validation message.

[Westbrook]

Also, you've got value and validation in the same place. Do you see a path towards validation being separate? Is there any benefit to that? Also, you currently list validation as a static, do you think there are use cases where we'd be able to submit validation on a component by component basis?

[Westbrook]

Separately, I'd love to see this moved into the repo as a PR. I think we're talking nuance vs need/desire, so being able to comment inline, get tests running, gets docs building, etc would be a great way to fast forward the review process.

[calebdwilliams]

Still working to grok all of this, but quick question is there any way to do this without emitting the as a sibling? This can unexpectedly change the validity of CSS selectors.

I think I'm following the ask and yes. I've added an example to the repo of a one-element switch component. The easiest way to implement a control is using an input (say for a design system), but it's definitely possible and I have a demo for that now.

Also, you've got value and validation in the same place. Do you see a path towards validation being separate? Is there any benefit to that? Also, you currently list validation as a static, do you think there are use cases where we'd be able to submit validation on a component by component basis?

They kind of are separate insofar as validators are composable. Conceptually I'm thinking that any given component likely has a given set of validations, hence adding them as static. Using this pattern you could potentially do that on a component-by-component basis. Using this pattern a developer should be able to easily write their own validators which I believe is valuable, but those validators can also be shared/composed.

This allows any given component to only import the validators they need (or use none). A great case for this might be a switch component which doesn't need to have a minlength or maxlength validator (and maybe none at all). I could see potentially breaking up the value and validation behaviors into separate mixins.

Separately, I'd love to see this moved into the repo as a PR. I think we're talking nuance vs need/desire, so being able to comment inline, get tests running, gets docs building, etc would be a great way to fast forward the review process.

Definitely. I'll likely do that after the holiday.

[calebdwilliams]

FWIW, I added the switch demo to the CodePen.

[michaelwarren1106]

i think i get it all, and i love the idea of the validator pattern. in some base class (like ComplexFormControl) i would probably end up implementing some optional registerValidation() function that would accept an array of custom from-the-outside validators that get added to the validation provided by the ComplexFormControl component so that devs that consume the <complex-demo> comp can add more validation as needed. so as long as this approach would allow such i think it’s great