feat: add CustomStateSet

Author: calebdwilliams

Diff for: README.md

@@ -27,6 +27,11 @@ yarn:
 yarn add element-internals-polyfill
 ```
 
+skypack:
+```javascript
+import 'https://cdn.skypack.dev/element-internals-polyfill';
+```
+
 unpkg:
 ```javascript
 import 'https://unpkg.com/element-internals-polyfill';
@@ -127,6 +132,38 @@ In addition to form controls, `ElementInternals` will also surface several acces
 - `ariaValueNow`: 'aria-valuenow'
 - `ariaValueText`: 'aria-valuetext'
 
+### State API
+
+`ElementInternals` exposes an API for creating custom states on an element. For instance if a developer wanted to signify to users that an element was in state `foo`, they could call `internals.states.set('--foo')`. This would make the element match the selector `:--foo`. Unfortunately in non-supporting browsers this is an invalid selector and will throw an error in JS and would cause the parsing of a CSS rule to fail. As a result, this polyfill will add states using the `state--foo` attribute to the host element.
+
+In order to properly select these elements in CSS, you will need to duplicate your rule as follows:
+
+```css
+/** Supporting browsers */
+:--foo { 
+  color: rebeccapurple;
+}
+
+/** Polyfilled browsers */
+[state--foo] {
+  color: rebeccapurple;
+}
+```
+
+Trying to combine selectors like `:--foo, [state--foo]` will cause the parsing of the rule to fail because `:--foo` is an invalid selector. As a potential optimization, you can use CSS `@supports` as follows:
+
+```css
+@supports selector(:--foo) {
+  /** Native supporting code here */
+}
+
+@supports not selector([state--foo]) {
+  /** Code for polyfilled browsers here */
+}
+```
+
+Be sure to understand how your supported browsers work with CSS `@supports` before using the above strategy.
+
 ## Current limitations
 
 - Right now providing a cross-browser compliant version of `ElementInternals.reportValidity` is not supported. The method essentially behaves as a proxy for `ElementInternals.checkValidity`.

Diff for: package-lock.json

@@ -48,6 +48,7 @@
     "@open-wc/testing-helpers": "^1.7.1",
     "@rollup/plugin-node-resolve": "^7.1.3",
     "@rollup/plugin-typescript": "^6.0.0",
+    "@web/dev-server-esbuild": "^0.2.12",
     "@web/test-runner": "^0.12.16",
     "@web/test-runner-playwright": "^0.8.4",
     "babel-plugin-istanbul": "^6.0.0",

Diff for: package.json

@@ -0,0 +1,36 @@
+import { ICustomElement } from "./types";
+
+/** Save a reference to the ref for teh CustomStateSet */
+const customStateMap = new WeakMap<CustomStateSet, ICustomElement>();
+
+export class CustomStateSet extends Set<string> {
+  constructor(ref: ICustomElement) {
+    super();
+
+    customStateMap.set(this, ref);
+  }
+
+  add(state: string) {
+    if (!/^--/.exec(state) || typeof state !== 'string') {
+      throw new DOMException(`Failed to execute 'add' on 'CustomStateSet': The specified value ${state} must start with '--'.`);
+    }
+    const result = super.add(state);
+    const ref = customStateMap.get(this);
+    ref.toggleAttribute(`state${state}`, true);
+    return result;
+  }
+
+  clear() {
+    for (let [entry] of this.entries()) {
+      this.delete(entry);
+    }
+    super.clear();
+  }
+
+  delete(state: string) {
+    const result = super.delete(state);
+    const ref = customStateMap.get(this);
+    ref.toggleAttribute(`state${state}`, false);
+    return result;
+  }
+}

Diff for: src/CustomStateSet.ts

@@ -22,6 +22,7 @@ import { initAom } from './aom';
 import { ValidityState, reconcileValidty, setValid } from './ValidityState';
 import { deferUpgrade, observerCallback, observerConfig } from './mutation-observers';
 import { IElementInternals, ICustomElement, LabelsList } from './types';
+import { CustomStateSet } from './CustomStateSet';
 
 export class ElementInternals implements IElementInternals {
   ariaAtomic: string;
@@ -61,6 +62,8 @@ export class ElementInternals implements IElementInternals {
   ariaValueNow: string;
   ariaValueText: string;
 
+  states: CustomStateSet;
+
   static get isPolyfilled() {
     return true;
   }
@@ -71,6 +74,7 @@ export class ElementInternals implements IElementInternals {
     }
     const rootNode = ref.getRootNode();
     const validity = new ValidityState();
+    this.states = new CustomStateSet(ref);
     refMap.set(this, ref);
     validityMap.set(this, validity);
     internalsMap.set(ref, this);

Diff for: src/element-internals.ts

@@ -0,0 +1,42 @@
+import { fixture, html, expect, fixtureCleanup } from '@open-wc/testing';
+import { ICustomElement } from '../dist';
+import { CustomStateSet } from '../src/CustomStateSet';
+
+describe('CustomStateSet polyfill', () => {
+  let el: HTMLElement;
+  let set: CustomStateSet;
+
+  beforeEach(async () => {
+    el = await fixture(html`<div></div>`);
+    set = new CustomStateSet(el as ICustomElement);
+  });
+
+  afterEach(() => {
+    fixtureCleanup();
+  });
+
+  describe('it will add attributes', async () => {
+    set.add('--foo');
+    expect(el.hasAttribute('state--foo')).to.be.true;
+  });
+
+  describe('it will remove attributes', async () => {
+    set.add('--foo');
+    expect(el.hasAttribute('state--foo')).to.be.true;
+
+    set.delete('--foo');
+    expect(el.hasAttribute('state--foo')).to.be.false;
+  });
+
+  describe('it will clear all attributes', async () => {
+    set.add('--foo');
+    set.add('--bar');
+
+    expect(el.hasAttribute('state--foo')).to.be.true;
+    expect(el.hasAttribute('state--bar')).to.be.true;
+
+    set.clear();
+    expect(el.hasAttribute('state--foo')).to.be.false;
+    expect(el.hasAttribute('state--bar')).to.be.false;
+  });
+});

Diff for: test/CustomStateSet.test.ts

@@ -1,11 +1,9 @@
 import {
-  aTimeout,
   expect,
   fixture,
   fixtureCleanup,
   html,
 } from '@open-wc/testing';
-import { spy } from 'sinon';
 import '../dist/index.js';
 
 describe('ElementInternals polyfill behavior', () => {

Diff for: test/polyfilledBrowsers.test.js

@@ -0,0 +1,5 @@
+import { esbuildPlugin } from '@web/dev-server-esbuild';
+
+export default {
+  plugins: [esbuildPlugin({ ts: true, target: 'auto' })],
+};