@material/web 0.1.0-alpha.1 → 1.0.0-pre.0

package/radio/lib/single-selection-controller.d.ts

@@ -1,167 +1,80 @@
 /**
  * @license
- * Copyright 2020 Google LLC
+ * Copyright 2022 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import { ReactiveController } from 'lit';
 /**
- * Set of checkable elements with added metadata
+ * An element that supports single-selection with `SingleSelectionController`.
  */
-export declare class SingleSelectionSet {
-    selected: CheckableElement | null;
-    ordered: CheckableElement[] | null;
-    readonly set: Set<CheckableElement>;
-}
-/**
- * Element that is checkable consumed by
- * `SingleSelectionController` and `SingleSelectionSet`
- */
-export declare type CheckableElement = HTMLElement & {
-    name: string;
+export interface SingleSelectionElement extends HTMLElement {
+    /**
+     * Whether or not the element is selected.
+     */
     checked: boolean;
-    formElementTabIndex?: number;
-};
+}
 /**
- * Controller that provides behavior similar to a native `<input type="radio">`
- * group.
- *
- * Behaviors:
+ * A `ReactiveController` that provides root node-scoped single selection for
+ * elements, similar to native `<input type="radio">` selection.
  *
- * - Selection via key navigation (currently LTR is supported)
- * - Deselection of other grouped, checkable controls upon selection
- * - Grouping of checkable elements by name
- *   - Defaults grouping scope to host shadow root
- *   - Document-wide scoping enabled
- * - Land focus only on checked element. Focuses leading element when none
- *   checked.
+ * To use, elements should add the controller and call
+ * `selectionController.handleCheckedChange()` in a getter/setter. This must
+ * be synchronous to match native behavior.
  *
- * Intended Usage:
+ * @example
+ * const CHECKED = Symbol('checked');
  *
- * ```ts
- * class MyElement extends HTMLElement {
- *   private selectionController: SingleSelectionController | null = null;
- *   name = "";
- *   global = false;
- *
- *   private _checked = false;
+ * class MyToggle extends LitElement {
+ *   get checked() { return this[CHECKED]; }
  *   set checked(checked: boolean) {
- *     const oldVal = this._checked;
- *     if (checked === oldVal) return;
- *
- *     this._checked = checked;
- *
- *     if (this.selectionController) {
- *       this.selectionController.update(this)
+ *     const oldValue = this.checked;
+ *     if (oldValue === checked) {
+ *       return;
  *     }
- *   }
  *
- *   get checked() {
- *     return this._checked;
+ *     this[CHECKED] = checked;
+ *     this.selectionController.handleCheckedChange();
+ *     this.requestUpdate('checked', oldValue);
  *   }
  *
- *   connectedCallback() {
- *     this.selectionController = SelectionController.getController(this);
- *     this.selectionController.register(this);
- *     this.selectionController.update(this);
- *   }
+ *   [CHECKED] = false;
+ *
+ *   private selectionController = new SingleSelectionController(this);
  *
- *   disconnectedCallback() {
- *     this.selectionController!.unregister(this);
- *     this.selectionController = null;
+ *   constructor() {
+ *     super();
+ *     this.addController(this.selectionController);
  *   }
  * }
- * ```
  */
-export declare class SingleSelectionController {
-    private readonly sets;
-    private focusedSet;
-    private mouseIsDown;
-    /**
-     * Get a controller for the given element. If no controller exists, one will
-     * be created. Defaults to getting the controller scoped to the element's root
-     * node shadow root unless `element.global` is true. Then, it will get a
-     * `window.document`-scoped controller.
-     *
-     * @param element Element from which to get / create a SelectionController. If
-     *     `element.global` is true, it gets a selection controller scoped to
-     *     `window.document`.
-     */
-    static getController(element: HTMLElement | HTMLElement & {
-        global: boolean;
-    }): SingleSelectionController;
-    constructor(element: Node);
-    protected keyDownHandler(e: KeyboardEvent): void;
-    protected mousedownHandler(): void;
-    protected mouseupHandler(): void;
-    /**
-     * Whether or not the controller controls  the given element.
-     *
-     * @param element element to check
-     */
-    has(element: CheckableElement): boolean;
-    /**
-     * Selects and returns the controlled element previous to the given element in
-     * document position order. See
-     * [Node.compareDocumentPosition](https://developer.mozilla.org/en-US/docs/Web/API/Node/compareDocumentPosition).
-     *
-     * @param element element relative from which preceding element is fetched
-     */
-    selectPrevious(element: CheckableElement): CheckableElement;
-    /**
-     * Selects and returns the controlled element next to the given element in
-     * document position order. See
-     * [Node.compareDocumentPosition](https://developer.mozilla.org/en-US/docs/Web/API/Node/compareDocumentPosition).
-     *
-     * @param element element relative from which following element is fetched
-     */
-    selectNext(element: CheckableElement): CheckableElement;
-    select(element: CheckableElement): void;
-    /**
-     * Focuses the selected element in the given element's selection set. User's
-     * mouse selection will override this focus.
-     *
-     * @param element Element from which selection set is derived and subsequently
-     *     focused.
-     * @deprecated update() method now handles focus management by setting
-     *     appropriate tabindex to form element.
-     */
-    focus(element: CheckableElement): void;
-    /**
-     * @return Returns true if atleast one radio is selected in the radio group.
-     */
-    isAnySelected(element: CheckableElement): boolean;
-    /**
-     * Returns the elements in the given element's selection set in document
-     * position order.
-     * [Node.compareDocumentPosition](https://developer.mozilla.org/en-US/docs/Web/API/Node/compareDocumentPosition).
-     *
-     * @param element Element from which selection set is derived and subsequently
-     *     ordered.
-     */
-    getOrdered(element: CheckableElement): CheckableElement[];
+export declare class SingleSelectionController implements ReactiveController {
+    private readonly host;
+    private focused;
+    private root;
+    constructor(host: SingleSelectionElement);
+    hostConnected(): void;
+    hostDisconnected(): void;
     /**
-     * Gets the selection set of the given name and creates one if it does not yet
-     * exist.
-     *
-     * @param name Name of set
+     * Should be called whenever the host's `checked` property changes
+     * synchronously.
      */
-    getSet(name: string): SingleSelectionSet;
+    handleCheckedChange(): void;
+    private readonly handleFocusIn;
+    private readonly handleFocusOut;
+    private uncheckSiblings;
     /**
-     * Register the element in the selection controller.
-     *
-     * @param element Element to register. Registers in set of `element.name`.
+     * Updates the `tabindex` of the host and its siblings.
      */
-    register(element: CheckableElement): void;
+    private updateTabIndices;
     /**
-     * Unregister the element from selection controller.
-     *
-     * @param element Element to register. Registers in set of `element.name`.
+     * Retrieves all siblings in the host element's root with the same `name`
+     * attribute.
      */
-    unregister(element: CheckableElement): void;
+    private getNamedSiblings;
     /**
-     * Unselects other elements in element's set if element is checked. Noop
-     * otherwise.
-     *
-     * @param element Element from which to calculate selection controller update.
+     * Handles arrow key events from the host. Using the arrow keys will
+     * select and check the next or previous sibling with the host's
+     * `name` attribute.
      */
-    update(element: CheckableElement): void;
+    private readonly handleKeyDown;
 }

package/radio/lib/single-selection-controller.js

@@ -1,289 +1,193 @@
 /**
  * @license
- * Copyright 2020 Google LLC
+ * Copyright 2022 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-// Style preference for leading underscores.
-// tslint:disable:strip-private-property-underscore
 /**
- * Unique symbol for marking roots
- */
-const selectionController = Symbol('selection controller');
-/**
- * Set of checkable elements with added metadata
- */
-export class SingleSelectionSet {
-    constructor() {
-        this.selected = null;
-        this.ordered = null;
-        this.set = new Set();
-    }
-}
-/**
- * Controller that provides behavior similar to a native `<input type="radio">`
- * group.
- *
- * Behaviors:
- *
- * - Selection via key navigation (currently LTR is supported)
- * - Deselection of other grouped, checkable controls upon selection
- * - Grouping of checkable elements by name
- *   - Defaults grouping scope to host shadow root
- *   - Document-wide scoping enabled
- * - Land focus only on checked element. Focuses leading element when none
- *   checked.
+ * A `ReactiveController` that provides root node-scoped single selection for
+ * elements, similar to native `<input type="radio">` selection.
  *
- * Intended Usage:
+ * To use, elements should add the controller and call
+ * `selectionController.handleCheckedChange()` in a getter/setter. This must
+ * be synchronous to match native behavior.
  *
- * ```ts
- * class MyElement extends HTMLElement {
- *   private selectionController: SingleSelectionController | null = null;
- *   name = "";
- *   global = false;
+ * @example
+ * const CHECKED = Symbol('checked');
  *
- *   private _checked = false;
+ * class MyToggle extends LitElement {
+ *   get checked() { return this[CHECKED]; }
  *   set checked(checked: boolean) {
- *     const oldVal = this._checked;
- *     if (checked === oldVal) return;
- *
- *     this._checked = checked;
- *
- *     if (this.selectionController) {
- *       this.selectionController.update(this)
+ *     const oldValue = this.checked;
+ *     if (oldValue === checked) {
+ *       return;
  *     }
- *   }
  *
- *   get checked() {
- *     return this._checked;
+ *     this[CHECKED] = checked;
+ *     this.selectionController.handleCheckedChange();
+ *     this.requestUpdate('checked', oldValue);
  *   }
  *
- *   connectedCallback() {
- *     this.selectionController = SelectionController.getController(this);
- *     this.selectionController.register(this);
- *     this.selectionController.update(this);
- *   }
+ *   [CHECKED] = false;
  *
- *   disconnectedCallback() {
- *     this.selectionController!.unregister(this);
- *     this.selectionController = null;
+ *   private selectionController = new SingleSelectionController(this);
+ *
+ *   constructor() {
+ *     super();
+ *     this.addController(this.selectionController);
  *   }
  * }
- * ```
  */
 export class SingleSelectionController {
-    constructor(element) {
-        this.sets = {};
-        this.focusedSet = null;
-        this.mouseIsDown = false;
-        element.addEventListener('keydown', (e) => {
-            this.keyDownHandler(e);
-        });
-        element.addEventListener('mousedown', () => {
-            this.mousedownHandler();
-        });
-        element.addEventListener('mouseup', () => {
-            this.mouseupHandler();
-        });
-    }
-    /**
-     * Get a controller for the given element. If no controller exists, one will
-     * be created. Defaults to getting the controller scoped to the element's root
-     * node shadow root unless `element.global` is true. Then, it will get a
-     * `window.document`-scoped controller.
-     *
-     * @param element Element from which to get / create a SelectionController. If
-     *     `element.global` is true, it gets a selection controller scoped to
-     *     `window.document`.
-     */
-    static getController(element) {
-        const useGlobal = !('global' in element) || ('global' in element && element.global);
-        const root = useGlobal ? document :
-            element.getRootNode();
-        let controller = root[selectionController];
-        if (controller === undefined) {
-            controller = new SingleSelectionController(root);
-            root[selectionController] = controller;
-        }
-        return controller;
-    }
-    keyDownHandler(e) {
-        const element = e.target;
-        if (!('checked' in element)) {
-            return;
-        }
-        if (!this.has(element)) {
-            return;
-        }
-        if (e.key == 'ArrowRight' || e.key == 'ArrowDown') {
-            this.selectNext(element);
-        }
-        else if (e.key == 'ArrowLeft' || e.key == 'ArrowUp') {
-            this.selectPrevious(element);
+    constructor(host) {
+        this.host = host;
+        this.focused = false;
+        this.root = null;
+        this.handleFocusIn = () => {
+            this.focused = true;
+            this.updateTabIndices();
+        };
+        this.handleFocusOut = () => {
+            this.focused = false;
+            this.updateTabIndices();
+        };
+        /**
+         * Handles arrow key events from the host. Using the arrow keys will
+         * select and check the next or previous sibling with the host's
+         * `name` attribute.
+         */
+        this.handleKeyDown = (event) => {
+            const isDown = event.key === 'ArrowDown';
+            const isUp = event.key === 'ArrowUp';
+            const isLeft = event.key === 'ArrowLeft';
+            const isRight = event.key === 'ArrowRight';
+            // Ignore non-arrow keys
+            if (!isLeft && !isRight && !isDown && !isUp) {
+                return;
+            }
+            // Don't try to select another sibling if there aren't any.
+            const siblings = this.getNamedSiblings();
+            if (!siblings.length) {
+                return;
+            }
+            // Prevent default interactions on the element for arrow keys,
+            // since this controller will introduce new behavior.
+            event.preventDefault();
+            // Check if moving forwards or backwards
+            const isRtl = getComputedStyle(this.host).direction === 'rtl';
+            const forwards = isRtl ? isLeft || isDown : isRight || isDown;
+            const hostIndex = siblings.indexOf(this.host);
+            let nextIndex = forwards ? hostIndex + 1 : hostIndex - 1;
+            // Search for the next sibling that is not disabled to select.
+            // If we return to the host index, there is nothing to select.
+            while (nextIndex !== hostIndex) {
+                if (nextIndex >= siblings.length) {
+                    // Return to start if moving past the last item.
+                    nextIndex = 0;
+                }
+                else if (nextIndex < 0) {
+                    // Go to end if moving before the first item.
+                    nextIndex = siblings.length - 1;
+                }
+                // Check if the next sibling is disabled. If so,
+                // move the index and continue searching.
+                const nextSibling = siblings[nextIndex];
+                if (nextSibling.hasAttribute('disabled')) {
+                    if (forwards) {
+                        nextIndex++;
+                    }
+                    else {
+                        nextIndex--;
+                    }
+                    continue;
+                }
+                // Uncheck and remove focusability from other siblings.
+                for (const sibling of siblings) {
+                    if (sibling !== nextSibling) {
+                        sibling.checked = false;
+                        sibling.tabIndex = -1;
+                    }
+                }
+                // The next sibling should be checked and focused.
+                nextSibling.checked = true;
+                nextSibling.removeAttribute('tabindex');
+                nextSibling.focus();
+                break;
+            }
+        };
+    }
+    hostConnected() {
+        this.root = this.host.getRootNode();
+        this.host.addEventListener('keydown', this.handleKeyDown);
+        this.host.addEventListener('focusin', this.handleFocusIn);
+        this.host.addEventListener('focusout', this.handleFocusOut);
+        if (this.host.checked) {
+            // Uncheck other siblings when attached if already checked. This mimics
+            // native <input type="radio"> behavior.
+            this.uncheckSiblings();
         }
+        // Update for the newly added host.
+        this.updateTabIndices();
     }
-    mousedownHandler() {
-        this.mouseIsDown = true;
-    }
-    mouseupHandler() {
-        this.mouseIsDown = false;
+    hostDisconnected() {
+        this.host.removeEventListener('keydown', this.handleKeyDown);
+        this.host.removeEventListener('focusin', this.handleFocusIn);
+        this.host.removeEventListener('focusout', this.handleFocusOut);
+        // Update for siblings that are still connected.
+        this.updateTabIndices();
+        this.root = null;
     }
     /**
-     * Whether or not the controller controls  the given element.
-     *
-     * @param element element to check
+     * Should be called whenever the host's `checked` property changes
+     * synchronously.
      */
-    has(element) {
-        const set = this.getSet(element.name);
-        return set.set.has(element);
-    }
-    /**
-     * Selects and returns the controlled element previous to the given element in
-     * document position order. See
-     * [Node.compareDocumentPosition](https://developer.mozilla.org/en-US/docs/Web/API/Node/compareDocumentPosition).
-     *
-     * @param element element relative from which preceding element is fetched
-     */
-    selectPrevious(element) {
-        const order = this.getOrdered(element);
-        const i = order.indexOf(element);
-        const previous = order[i - 1] || order[order.length - 1];
-        this.select(previous);
-        return previous;
-    }
-    /**
-     * Selects and returns the controlled element next to the given element in
-     * document position order. See
-     * [Node.compareDocumentPosition](https://developer.mozilla.org/en-US/docs/Web/API/Node/compareDocumentPosition).
-     *
-     * @param element element relative from which following element is fetched
-     */
-    selectNext(element) {
-        const order = this.getOrdered(element);
-        const i = order.indexOf(element);
-        const next = order[i + 1] || order[0];
-        this.select(next);
-        return next;
-    }
-    select(element) {
-        element.click();
-    }
-    /**
-     * Focuses the selected element in the given element's selection set. User's
-     * mouse selection will override this focus.
-     *
-     * @param element Element from which selection set is derived and subsequently
-     *     focused.
-     * @deprecated update() method now handles focus management by setting
-     *     appropriate tabindex to form element.
-     */
-    focus(element) {
-        // Only manage focus state when using keyboard
-        if (this.mouseIsDown) {
+    handleCheckedChange() {
+        if (!this.host.checked) {
             return;
         }
-        const set = this.getSet(element.name);
-        const currentFocusedSet = this.focusedSet;
-        this.focusedSet = set;
-        if (currentFocusedSet != set && set.selected && set.selected != element) {
-            set.selected.focus();
-        }
+        this.uncheckSiblings();
+        this.updateTabIndices();
     }
-    /**
-     * @return Returns true if atleast one radio is selected in the radio group.
-     */
-    isAnySelected(element) {
-        const set = this.getSet(element.name);
-        for (const e of set.set) {
-            if (e.checked) {
-                return true;
+    uncheckSiblings() {
+        for (const sibling of this.getNamedSiblings()) {
+            if (sibling !== this.host) {
+                sibling.checked = false;
             }
         }
-        return false;
-    }
-    /**
-     * Returns the elements in the given element's selection set in document
-     * position order.
-     * [Node.compareDocumentPosition](https://developer.mozilla.org/en-US/docs/Web/API/Node/compareDocumentPosition).
-     *
-     * @param element Element from which selection set is derived and subsequently
-     *     ordered.
-     */
-    getOrdered(element) {
-        const set = this.getSet(element.name);
-        if (!set.ordered) {
-            set.ordered = Array.from(set.set);
-            set.ordered.sort((a, b) => a.compareDocumentPosition(b) == Node.DOCUMENT_POSITION_PRECEDING ?
-                1 :
-                0);
-        }
-        return set.ordered;
     }
     /**
-     * Gets the selection set of the given name and creates one if it does not yet
-     * exist.
-     *
-     * @param name Name of set
+     * Updates the `tabindex` of the host and its siblings.
      */
-    getSet(name) {
-        if (!this.sets[name]) {
-            this.sets[name] = new SingleSelectionSet();
+    updateTabIndices() {
+        // There are three tabindex states for a group of elements:
+        // 1. If any are checked, that element is focusable.
+        const siblings = this.getNamedSiblings();
+        const checkedSibling = siblings.find(sibling => sibling.checked);
+        // 2. If an element is focused, the others are no longer focusable.
+        if (checkedSibling || this.focused) {
+            const focusable = checkedSibling || this.host;
+            focusable.removeAttribute('tabindex');
+            for (const sibling of siblings) {
+                if (sibling !== focusable) {
+                    sibling.tabIndex = -1;
+                }
+            }
+            return;
         }
-        return this.sets[name];
-    }
-    /**
-     * Register the element in the selection controller.
-     *
-     * @param element Element to register. Registers in set of `element.name`.
-     */
-    register(element) {
-        // TODO(b/168546148): Remove accessing 'name' via getAttribute() when new
-        // base class is created without single selection controller. Component
-        // maybe booted up after it is connected to DOM in which case properties
-        // (including `name`) are not updated yet.
-        const name = element.name || element.getAttribute('name') || '';
-        const set = this.getSet(name);
-        set.set.add(element);
-        set.ordered = null;
-    }
-    /**
-     * Unregister the element from selection controller.
-     *
-     * @param element Element to register. Registers in set of `element.name`.
-     */
-    unregister(element) {
-        const set = this.getSet(element.name);
-        set.set.delete(element);
-        set.ordered = null;
-        if (set.selected == element) {
-            set.selected = null;
+        // 3. If none are checked or focused, all are focusable.
+        for (const sibling of siblings) {
+            sibling.removeAttribute('tabindex');
         }
     }
     /**
-     * Unselects other elements in element's set if element is checked. Noop
-     * otherwise.
-     *
-     * @param element Element from which to calculate selection controller update.
+     * Retrieves all siblings in the host element's root with the same `name`
+     * attribute.
      */
-    update(element) {
-        const set = this.getSet(element.name);
-        if (element.checked) {
-            for (const e of set.set) {
-                if (e == element) {
-                    continue;
-                }
-                e.checked = false;
-            }
-            set.selected = element;
-        }
-        // When tabbing through land focus on the checked radio in the group.
-        if (this.isAnySelected(element)) {
-            for (const e of set.set) {
-                if (e.formElementTabIndex === undefined) {
-                    break;
-                }
-                e.formElementTabIndex = e.checked ? 0 : -1;
-            }
+    getNamedSiblings() {
+        const name = this.host.getAttribute('name');
+        if (!name || !this.root) {
+            return [];
         }
+        return Array.from(this.root.querySelectorAll(`[name="${name}"]`));
     }
 }
 //# sourceMappingURL=single-selection-controller.js.map