Feat/prop descriptions

.changeset/selfish-ears-flash.md

@@ -0,0 +1,9 @@
+---
+'@lion/form-core': minor
+'@lion/input-range': minor
+'@lion/listbox': minor
+'@lion/radio-group': minor
+'@lion/select': minor
+---
+
+member descriptions for editors and api tables

.changeset/short-llamas-share.md

@@ -0,0 +1,5 @@
+---
+'@lion/form-core': patch
+---
+
+support [focused-visible] when focusable node within matches :focus-visible

packages/form-core/src/FocusMixin.js

@@ -1,25 +1,50 @@
 import { dedupeMixin } from '@lion/core';
-import { FormControlMixin } from './FormControlMixin.js';
+
+const windowWithOptionalPolyfill = /** @type {Window & typeof globalThis & {applyFocusVisiblePolyfill?: function}} */ (window);
+const polyfilledNodes = new WeakMap();
+
+/**
+ * @param {Node} node
+ */
+function applyFocusVisiblePolyfillWhenNeeded(node) {
+  if (windowWithOptionalPolyfill.applyFocusVisiblePolyfill && !polyfilledNodes.has(node)) {
+    windowWithOptionalPolyfill.applyFocusVisiblePolyfill(node);
+    polyfilledNodes.set(node, undefined);
+  }
+}
+
 /**
  * @typedef {import('../types/FocusMixinTypes').FocusMixin} FocusMixin
  * @type {FocusMixin}
  * @param {import('@open-wc/dedupe-mixin').Constructor<import('@lion/core').LitElement>} superclass
  */
 const FocusMixinImplementation = superclass =>
-  class FocusMixin extends FormControlMixin(superclass) {
+  class FocusMixin extends superclass {
     /** @type {any} */
     static get properties() {
       return {
-        focused: {
-          type: Boolean,
-          reflect: true,
-        },
+        focused: { type: Boolean, reflect: true },
+        focusedVisible: { type: Boolean, reflect: true, attribute: 'focused-visible' },
       };
     }
 
     constructor() {
       super();
+
+      /**
+       * Whether the focusable element within (`._focusableNode`) is focused.
+       * Reflects to attribute '[focused]' as a styling hook
+       * @type {boolean}
+       */
       this.focused = false;
+
+      /**
+       * Whether the focusable element within (`._focusableNode`) matches ':focus-visible'
+       * Reflects to attribute '[focused-visible]' as a styling hook
+       * See: https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible
+       * @type {boolean}
+       */
+      this.focusedVisible = false;
     }
 
     connectedCallback() {
@@ -32,38 +57,63 @@ const FocusMixinImplementation = superclass =>
       this.__teardownEventsForFocusMixin();
     }
 
+    /**
+     * Calls `focus()` on focusable element within
+     */
     focus() {
-      const native = this._inputNode;
-      if (native) {
-        native.focus();
-      }
+      this._focusableNode?.focus();
     }
 
+    /**
+     * Calls `blur()` on focusable element within
+     */
     blur() {
-      const native = this._inputNode;
-      if (native) {
-        native.blur();
-      }
+      this._focusableNode?.blur();
+    }
+
+    /**
+     * The focusable element:
+     * could be an input, textarea, select, button or any other element with tabindex > -1
+     * @protected
+     * @type {HTMLElement}
+     */
+    get _focusableNode() {
+      // TODO: [v1]: remove return of _inputNode (it's now here for backwards compatibility)
+      // @ts-expect-error see above
+      return /** @type {HTMLElement} */ (this._inputNode || document.createElement('input'));
     }
 
     /**
      * @private
      */
     __onFocus() {
       this.focused = true;
+
+      if (typeof windowWithOptionalPolyfill.applyFocusVisiblePolyfill === 'function') {
+        this.focusedVisible = this._focusableNode.hasAttribute('data-focus-visible-added');
+      } else
+        try {
+          // Safari throws when matches is called
+          this.focusedVisible = this._focusableNode.matches(':focus-visible');
+        } catch (_) {
+          this.focusedVisible = false;
+        }
     }
 
     /**
      * @private
      */
     __onBlur() {
       this.focused = false;
+      this.focusedVisible = false;
     }
 
     /**
      * @private
      */
     __registerEventsForFocusMixin() {
+      applyFocusVisiblePolyfillWhenNeeded(this.getRootNode());
+
       /**
        * focus
        * @param {Event} ev
@@ -72,7 +122,7 @@ const FocusMixinImplementation = superclass =>
         ev.stopPropagation();
         this.dispatchEvent(new Event('focus'));
       };
-      this._inputNode.addEventListener('focus', this.__redispatchFocus);
+      this._focusableNode.addEventListener('focus', this.__redispatchFocus);
 
       /**
        * blur
@@ -82,7 +132,7 @@ const FocusMixinImplementation = superclass =>
         ev.stopPropagation();
         this.dispatchEvent(new Event('blur'));
       };
-      this._inputNode.addEventListener('blur', this.__redispatchBlur);
+      this._focusableNode.addEventListener('blur', this.__redispatchBlur);
 
       /**
        * focusin
@@ -93,7 +143,7 @@ const FocusMixinImplementation = superclass =>
         this.__onFocus();
         this.dispatchEvent(new Event('focusin', { bubbles: true, composed: true }));
       };
-      this._inputNode.addEventListener('focusin', this.__redispatchFocusin);
+      this._focusableNode.addEventListener('focusin', this.__redispatchFocusin);
 
       /**
        * focusout
@@ -104,30 +154,35 @@ const FocusMixinImplementation = superclass =>
         this.__onBlur();
         this.dispatchEvent(new Event('focusout', { bubbles: true, composed: true }));
       };
-      this._inputNode.addEventListener('focusout', this.__redispatchFocusout);
+      this._focusableNode.addEventListener('focusout', this.__redispatchFocusout);
     }
 
     /**
      * @private
      */
     __teardownEventsForFocusMixin() {
-      this._inputNode.removeEventListener(
+      this._focusableNode.removeEventListener(
         'focus',
         /** @type {EventListenerOrEventListenerObject} */ (this.__redispatchFocus),
       );
-      this._inputNode.removeEventListener(
+      this._focusableNode.removeEventListener(
         'blur',
         /** @type {EventListenerOrEventListenerObject} */ (this.__redispatchBlur),
       );
-      this._inputNode.removeEventListener(
+      this._focusableNode.removeEventListener(
         'focusin',
         /** @type {EventListenerOrEventListenerObject} */ (this.__redispatchFocusin),
       );
-      this._inputNode.removeEventListener(
+      this._focusableNode.removeEventListener(
         'focusout',
         /** @type {EventListenerOrEventListenerObject} */ (this.__redispatchFocusout),
       );
     }
   };
 
+/**
+ * For browsers that not support the [spec](https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible),
+ * be sure to load the polyfill into your application https://github.com/WICG/focus-visible
+ * (or go for progressive enhancement).
+ */
 export const FocusMixin = dedupeMixin(FocusMixinImplementation);