From 7ddddcabbf7fe53ebd76ed4df249e5cf5aae097e Mon Sep 17 00:00:00 2001
From: Richard Herman <1429781+GeekyEggo@users.noreply.github.com>
Date: Wed, 30 Oct 2024 19:11:26 +0000
Subject: [PATCH] feat: add sd-radio-group and sd-option (#66)

* feat: add sd-radio

* fix: equality checking

* feat: add support for typed options

* feat: add custom data for sd-option and sd-radio-list

* refactor: rename radio list to radio group

* docs: update JSDocs

* refactor: update element name

* refactor: update file name to reflect spacing

---------

Co-authored-by: Richard Herman <geekyeggo@users.noreply.github.com>
---
 .vscode/html.customData.json                  |  40 +++++
 src/common/__tests__/utils.test.ts            |  86 +++++++++-
 src/common/utils.ts                           |  27 ++++
 src/ui/components/index.ts                    |   4 +-
 src/ui/components/label.ts                    |  10 +-
 src/ui/components/option.ts                   |  75 +++++++++
 src/ui/components/radio-group.ts              | 149 ++++++++++++++++++
 .../{textfield.ts => text-field.ts}           |   4 +-
 src/ui/controllers/option-observer.ts         |  87 ++++++++++
 src/ui/mixins/input.ts                        |   2 +-
 src/ui/mixins/list.ts                         |  77 +++++++++
 src/ui/utils.ts                               |  10 ++
 12 files changed, 558 insertions(+), 13 deletions(-)
 create mode 100644 src/ui/components/option.ts
 create mode 100644 src/ui/components/radio-group.ts
 rename src/ui/components/{textfield.ts => text-field.ts} (98%)
 create mode 100644 src/ui/controllers/option-observer.ts
 create mode 100644 src/ui/mixins/list.ts

diff --git a/.vscode/html.customData.json b/.vscode/html.customData.json
index 497cd34c..b0b44e99 100644
--- a/.vscode/html.customData.json
+++ b/.vscode/html.customData.json
@@ -22,6 +22,46 @@
                 }
             ]
         },
+        {
+            "name": "sd-option",
+            "description": "Non-visual element that provides information for an option.",
+            "attributes": [
+                {
+                    "name": "disabled",
+                    "description": "Determines whether the option is disabled; default `false`.",
+                    "values": [{ "name": "disabled" }]
+                },
+                {
+                    "name": "type",
+                    "description": "Type of the value; allows for the value to be converted to a boolean or number.",
+                    "values": [{ "name": "boolean" }, { "name": "number" }, { "name": "string" }]
+                },
+                {
+                    "name": "value",
+                    "description": "Value of the option."
+                }
+            ]
+        },
+        {
+            "name": "sd-radio-list",
+            "description": "Element that offers persisting a value via a list of radio options.",
+            "attributes": [
+                {
+                    "name": "disabled",
+                    "description": "Determines whether the input is disabled; default `false`.",
+                    "values": [{ "name": "disabled" }]
+                },
+                {
+                    "name": "global",
+                    "description": "When `true`, the setting will be persisted in the global settings, otherwise it will be persisted in the action's settings; default `false`.",
+                    "values": [{ "name": "global" }]
+                },
+                {
+                    "name": "setting",
+                    "description": "Path to the setting where the value should be persisted, for example `name`."
+                }
+            ]
+        },
         {
             "name": "sd-switch",
             "description": "Element that offers persisting a `boolean` via a toggle switch.",
diff --git a/src/common/__tests__/utils.test.ts b/src/common/__tests__/utils.test.ts
index be23e934..762e808e 100644
--- a/src/common/__tests__/utils.test.ts
+++ b/src/common/__tests__/utils.test.ts
@@ -1,5 +1,5 @@
 import { PromiseCompletionSource } from "../promises";
-import { debounce, freeze, get, set } from "../utils";
+import { debounce, freeze, get, parseBoolean, parseNumber, set } from "../utils";
 
 /**
  * Provides assertions for {@link debounce}.
@@ -147,6 +147,90 @@ describe("get", () => {
 	});
 });
 
+/**
+ * Provides assertions for {@link parseBoolean}.
+ */
+describe("parseBoolean", () => {
+	/**
+	 * Asserts {@link parseBoolean} parses truthy values that represent `true`.
+	 */
+	test.each([
+		{},
+		true,
+		1,
+		"true",
+		"any",
+	])("%s is true", (value) => {
+		expect(parseBoolean(value)).toBe(true);
+	});
+
+	/**
+	 * Asserts {@link parseBoolean} parses truthy values that represent `false`.
+	 */
+	test.each([
+		undefined,
+		null,
+		false,
+		0,
+	])("%s is false", (value) => {
+		expect(parseBoolean(value)).toBe(false);
+	});
+});
+
+/**
+ * Provides assertions for {@link parseNumber}.
+ */
+describe("parseNumber", () => {
+	/**
+	 * Asserts {@link parseNumber} with values that can be parsed.
+	 */
+	test.each([
+		{
+			value: -1,
+			expected: -1,
+		},
+		{
+			value: 0,
+			expected: 0,
+		},
+		{
+			value: 1,
+			expected: 1,
+		},
+		{
+			value: "13",
+			expected: 13,
+		},
+		{
+			value: "25.0",
+			expected: 25,
+		},
+		{
+			value: "99.9",
+			expected: 99.9,
+		},
+		{
+			value: "100a",
+			expected: 100,
+		},
+	])("parses $value = $expected", ({ value, expected }) => {
+		expect(parseNumber(value)).toBe(expected);
+	});
+
+	/**
+	 * Asserts {@link parseNumber} with values that cannot be parsed.
+	 */
+	test.each([
+		undefined,
+		null,
+		"false",
+		"a123b",
+		{},
+	])("$value = undefined", (value) => {
+		expect(parseNumber(value)).toBeUndefined();
+	});
+});
+
 /**
  * Provides assertions for {@link set}.
  */
diff --git a/src/common/utils.ts b/src/common/utils.ts
index 0b3c4761..d0128091 100644
--- a/src/common/utils.ts
+++ b/src/common/utils.ts
@@ -55,6 +55,33 @@ export function get(path: string, source: unknown): unknown {
 	return props.reduce((obj, prop) => obj && obj[prop as keyof object], source);
 }
 
+/**
+ * Parses the specified value to a truthy boolean (using {@link https://stackoverflow.com/questions/784929/what-does-the-operator-do-in-javascript `!!` notation}).
+ * @param value Value to parse.
+ * @returns `true` when the value is truthy; otherwise `false`.
+ */
+export function parseBoolean(value: unknown): boolean | undefined {
+	return !!value;
+}
+
+/**
+ * Parses the specified value to a number (using {@link parseFloat}).
+ * @param value Value to parse.
+ * @returns The parsed value; otherwise `undefined`.
+ */
+export function parseNumber(value: unknown): number | undefined {
+	if (typeof value === "number") {
+		return value;
+	}
+
+	if (typeof value !== "string") {
+		return undefined;
+	}
+
+	value = parseFloat(value);
+	return typeof value === "number" && !isNaN(value) ? value : undefined;
+}
+
 /**
  * Sets the specified `value` on the `target` object at the desired property `path`.
  * @param path The path to the property to set.
diff --git a/src/ui/components/index.ts b/src/ui/components/index.ts
index 52419160..b9cf3cf6 100644
--- a/src/ui/components/index.ts
+++ b/src/ui/components/index.ts
@@ -1,4 +1,6 @@
 import "./field";
 import "./label";
+import "./option";
+import "./radio-group";
 import "./switch";
-import "./textfield";
+import "./text-field";
diff --git a/src/ui/components/label.ts b/src/ui/components/label.ts
index 729e388a..098c80b0 100644
--- a/src/ui/components/label.ts
+++ b/src/ui/components/label.ts
@@ -4,6 +4,7 @@ import { ifDefined } from "lit/directives/if-defined.js";
 import { createRef, ref } from "lit/directives/ref.js";
 
 import { isSDInputElement } from "../mixins/input";
+import { preventDoubleClickSelection } from "../utils";
 
 /**
  * Element that provides a label for input element.
@@ -49,14 +50,7 @@ export class SDLabelElement extends LitElement {
 	 * @inheritdoc
 	 */
 	public override render(): TemplateResult {
-		return html`<label
-			for=${ifDefined(this.htmlFor)}
-			@mousedown=${(ev: MouseEvent): void => {
-				// Disable text selection on double-click.
-				if (ev.detail > 1) {
-					ev.preventDefault();
-				}
-			}}
+		return html`<label for=${ifDefined(this.htmlFor)} @mousedown=${preventDoubleClickSelection}
 			><slot ${ref(this.#slotRef)}></slot>
 		</label>`;
 	}
diff --git a/src/ui/components/option.ts b/src/ui/components/option.ts
new file mode 100644
index 00000000..23654908
--- /dev/null
+++ b/src/ui/components/option.ts
@@ -0,0 +1,75 @@
+import { LitElement } from "lit";
+import { customElement, property } from "lit/decorators.js";
+
+import { parseBoolean, parseNumber } from "../../common/utils";
+
+/**
+ * Non-visual element that provides information for an option.
+ */
+@customElement("sd-option")
+export class SDOptionElement extends LitElement {
+	/**
+	 * Private backing field for {@link SDOptionElement.value}.
+	 */
+	#value: boolean | number | string | undefined;
+
+	/**
+	 * Determines whether the option is disabled; default `false`.
+	 */
+	@property({ type: Boolean })
+	public accessor disabled: boolean = false;
+
+	/**
+	 * Label that represents the option; read from the `innerText` of the element.
+	 * @returns The label.
+	 */
+	public get label(): string {
+		return this.innerText;
+	}
+
+	/**
+	 * Type of the value; allows for the value to be converted to a boolean or number.
+	 */
+	@property()
+	public accessor type: "boolean" | "number" | "string" = "string";
+
+	/**
+	 * Untyped value, as defined by the `value` attribute; use `value` property for the typed-value.
+	 */
+	@property({ attribute: "value" })
+	public accessor htmlValue: string | undefined = undefined;
+
+	/**
+	 * Value of the option.
+	 * @returns The value.
+	 */
+	public get value(): boolean | number | string | undefined {
+		return this.#value;
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	protected override willUpdate(_changedProperties: Map<PropertyKey, unknown>): void {
+		super.willUpdate(_changedProperties);
+
+		if (_changedProperties.has("type") || _changedProperties.has("value")) {
+			if (this.type === "boolean") {
+				this.#value = parseBoolean(this.htmlValue);
+			} else if (this.type === "number") {
+				this.#value = parseNumber(this.htmlValue);
+			} else {
+				this.#value = this.htmlValue;
+			}
+		}
+	}
+}
+
+declare global {
+	interface HTMLElementTagNameMap {
+		/**
+		 * Non-visual element that provides information for an option.
+		 */
+		"sd-option": SDOptionElement;
+	}
+}
diff --git a/src/ui/components/radio-group.ts b/src/ui/components/radio-group.ts
new file mode 100644
index 00000000..6d53d179
--- /dev/null
+++ b/src/ui/components/radio-group.ts
@@ -0,0 +1,149 @@
+import { css, html, LitElement, type TemplateResult } from "lit";
+import { customElement } from "lit/decorators.js";
+import { ifDefined } from "lit/directives/if-defined.js";
+import { repeat } from "lit/directives/repeat.js";
+
+import { Input } from "../mixins/input";
+import { List } from "../mixins/list";
+import { preventDoubleClickSelection } from "../utils";
+
+/**
+ * Element that offers persisting a value via a list of radio options.
+ */
+@customElement("sd-radiogroup")
+export class SDRadioGroupElement extends List(Input<boolean | number | string>(LitElement)) {
+	/**
+	 * @inheritdoc
+	 */
+	public static styles = [
+		super.styles ?? [],
+		css`
+			label {
+				display: flex;
+				align-items: center;
+			}
+
+			input {
+				/* Hide the input, whilst still allowing focus */
+				height: 0;
+				opacity: 0;
+				position: absolute;
+				width: 0;
+			}
+
+			/**
+			 * Radio button replacement.
+			 */
+
+			.indicator {
+				--size: calc(var(--size-m) - calc(var(--border-width-thin) * 2));
+				align-items: center;
+				border: var(--border-width-thin) solid var(--color-content-disabled);
+				border-radius: var(--rounding-full);
+				display: inline-flex;
+				height: var(--size);
+				justify-content: center;
+				margin: var(--space-xs) var(--space-xs) var(--space-xs) 0;
+				user-select: none;
+				width: var(--size);
+			}
+
+			/**
+			 * Checked.
+			 */
+
+			input:checked {
+				& + .indicator {
+					background: var(--color-surface-accent);
+					border-color: var(--color-content-disabled);
+					border-radius: var(--rounding-full);
+				}
+
+				& + .indicator::before {
+					content: "";
+					background: var(--color-surface-ondark);
+					border-radius: var(--rounding-full);
+					display: block;
+					height: var(--size-xs);
+					width: var(--size-xs);
+				}
+			}
+
+			/**
+			 * Disabled.
+			 */
+
+			label:has(input:disabled) {
+				color: var(--color-content-disabled);
+			}
+
+			input:disabled + .indicator {
+				border-color: var(--color-border-subtle-disabled);
+			}
+
+			/**
+			 * Checked + disabled.
+			 */
+
+			input:checked:disabled {
+				& + .indicator {
+					background-color: var(--color-surface-disabled);
+				}
+
+				& + .indicator::before {
+					background-color: var(--color-content-disabled);
+				}
+			}
+
+			/**
+			 * Focus
+			 */
+
+			input:focus-visible + .indicator {
+				box-shadow: var(--highlight-box-shadow);
+				outline: var(--highlight-outline--focus);
+				outline-offset: var(--highlight-outline-offset);
+			}
+		`,
+	];
+
+	/**
+	 * @inheritdoc
+	 */
+	public override render(): TemplateResult {
+		return html`
+			${repeat(
+				this.items,
+				({ key }) => key,
+				({ disabled, label, value }) => {
+					return html`
+						<label role="radio" @mousedown=${preventDoubleClickSelection}>
+							<input
+								name="radio"
+								type="radio"
+								value=${ifDefined(value)}
+								tabindex=${ifDefined(disabled ? undefined : 0)}
+								.checked=${this.value === value}
+								.disabled=${disabled}
+								@change=${(): void => {
+									this.value = value;
+								}}
+							/>
+							<span class="indicator"></span>
+							${label}
+						</label>
+					`;
+				},
+			)}
+		`;
+	}
+}
+
+declare global {
+	interface HTMLElementTagNameMap {
+		/**
+		 * Element that offers persisting a value via a list of radio options.
+		 */
+		"sd-radiogroup": SDRadioGroupElement;
+	}
+}
diff --git a/src/ui/components/textfield.ts b/src/ui/components/text-field.ts
similarity index 98%
rename from src/ui/components/textfield.ts
rename to src/ui/components/text-field.ts
index a5bfe140..05fe84ae 100644
--- a/src/ui/components/textfield.ts
+++ b/src/ui/components/text-field.ts
@@ -119,8 +119,8 @@ export class SDTextFieldElement extends Input<string>(LitElement) {
 			placeholder=${ifDefined(this.placeholder)}
 			?disabled=${this.disabled}
 			?required=${this.#userHasInteracted && this.required}
-			.type=${this.type || "text"}
-			.value=${this.value || ""}
+			.type=${this.type ?? "text"}
+			.value=${this.value ?? ""}
 			@blur=${(): void => {
 				this.#userHasInteracted = true;
 			}}
diff --git a/src/ui/controllers/option-observer.ts b/src/ui/controllers/option-observer.ts
new file mode 100644
index 00000000..27c2e103
--- /dev/null
+++ b/src/ui/controllers/option-observer.ts
@@ -0,0 +1,87 @@
+import { ReactiveController, ReactiveControllerHost } from "lit";
+
+import { SDOptionElement } from "../components/option";
+
+/**
+ * Controller for tracking {@link SDOptionElement} elements within a host.
+ */
+export class OptionObserver implements ReactiveController {
+	/**
+	 * Current options within the host.
+	 */
+	public readonly options: SDOptionElement[];
+
+	/**
+	 * Host this controller is attached to.
+	 */
+	readonly #host: HTMLElement & ReactiveControllerHost;
+
+	/**
+	 * Underlying mutation observer monitoring changes to the shadow DOM.
+	 */
+	readonly #observer: MutationObserver;
+
+	/**
+	 * Initializes a new instance of the {@link OptionObserver} class.
+	 * @param host Host to attached to.
+	 */
+	constructor(host: HTMLElement & ReactiveControllerHost) {
+		this.#host = host;
+		this.#observer = new MutationObserver((mutations: MutationRecord[]) => this.#onMutation(mutations));
+
+		// Add the controller, and determine the initial set of options.
+		this.#host.addController(this);
+		this.options = Array.from(this.#host.querySelectorAll("sd-option"));
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public hostConnected(): void {
+		this.#observer.observe(this.#host, {
+			childList: true,
+		});
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public hostDisconnected(): void {
+		this.#observer.disconnect();
+	}
+
+	/**
+	 * Handles a mutation on the host's shadow DOM, updating the tracked collection of {@link SDOptionElement}.
+	 * @param mutations Mutations that occurred.
+	 */
+	#onMutation(mutations: MutationRecord[]): void {
+		let changed = false;
+
+		mutations.forEach((mutation) => {
+			// Added.
+			for (const added of mutation.addedNodes) {
+				if (added instanceof SDOptionElement) {
+					changed = true;
+					this.options.push(added);
+				}
+			}
+
+			// Removed.
+			mutation.removedNodes.forEach((node) => {
+				if (!(node instanceof SDOptionElement)) {
+					return;
+				}
+
+				const index = this.options.indexOf(node);
+				if (index !== -1) {
+					changed = true;
+					this.options.splice(index, 1);
+				}
+			});
+		});
+
+		if (changed) {
+			this.#host.requestUpdate();
+		}
+	}
+}
diff --git a/src/ui/mixins/input.ts b/src/ui/mixins/input.ts
index 9dc209e0..0dd725af 100644
--- a/src/ui/mixins/input.ts
+++ b/src/ui/mixins/input.ts
@@ -139,7 +139,7 @@ export const Input = <TValue extends JsonValue, TBase extends Constructor<LitEle
 		 * @returns `true` when the value changed; otherwise `false`.
 		 */
 		#setValue(newValue: TValue | undefined): boolean {
-			if (this.#value == newValue) {
+			if (this.#value === newValue) {
 				return false;
 			}
 
diff --git a/src/ui/mixins/list.ts b/src/ui/mixins/list.ts
new file mode 100644
index 00000000..a26572ba
--- /dev/null
+++ b/src/ui/mixins/list.ts
@@ -0,0 +1,77 @@
+import { LitElement } from "lit";
+
+import type { Constructor } from "../../common/utils";
+import type { SDOptionElement } from "../components/option";
+import { OptionObserver } from "../controllers/option-observer";
+
+/**
+ * List mixin that provides common functionality for input elements that have options.
+ * @param superClass Class the mixin extends.
+ * @returns List mixin class.
+ */
+export const List = <TBase extends Constructor<LitElement> = typeof LitElement>(
+	superClass: TBase,
+): Constructor<SDListElement> & TBase => {
+	/**
+	 * List mixin that provides common functionality for input elements that have options.
+	 */
+	class ListMixin extends superClass {
+		/**
+		 * Mutation observer for monitoring {@link SDOptionElement} within the shadow DOM of this instance.
+		 */
+		readonly #domObserver = new OptionObserver(this);
+
+		/**
+		 * Gets the items within the list.
+		 * @returns The list items.
+		 */
+		public get items(): Iterable<ListItem> {
+			return this.#domObserver.options.map((opt: SDOptionElement): ListItem => {
+				return {
+					disabled: opt.disabled,
+					key: opt,
+					label: opt.label,
+					value: opt.value,
+				};
+			});
+		}
+	}
+
+	return ListMixin as unknown as Constructor<SDListElement> & TBase;
+};
+
+/**
+ * List mixin that provides common functionality for input elements that have options.
+ */
+export declare class SDListElement extends LitElement {
+	/**
+	 * Gets the items within the list.
+	 * @returns The list items.
+	 */
+	public get items(): Iterable<ListItem>;
+}
+
+/**
+ * Information about an item within a list.
+ */
+export type ListItem = {
+	/**
+	 * Determines whether the list item is disabled.
+	 */
+	disabled: boolean;
+
+	/**
+	 * Unique key that identifies the list item.
+	 */
+	key: unknown;
+
+	/**
+	 * Label of the list item.
+	 */
+	label: string;
+
+	/**
+	 * Value of the list item.
+	 */
+	value: boolean | number | string | undefined;
+};
diff --git a/src/ui/utils.ts b/src/ui/utils.ts
index f37665e3..c8a88df2 100644
--- a/src/ui/utils.ts
+++ b/src/ui/utils.ts
@@ -1,3 +1,13 @@
+/**
+ * Prevents the default behavior occurring when a double click occurs, preventing text-selection.
+ * @param ev Source event.
+ */
+export function preventDoubleClickSelection(ev: MouseEvent): void {
+	if (ev.detail > 1) {
+		ev.preventDefault();
+	}
+}
+
 /**
  * An event triggered by an HTML input element, that allows for the target to be typed.
  */