@timmo001/groundwork-ui 0.0.0-stage → 0.3.0

package/src/gw-segmented.ts

@@ -0,0 +1,301 @@
+/**
+ * `gw-segmented`: picks one of a few options, as a row of radio buttons.
+ * Docs: https://groundwork.timmo.dev/components/actions/#segmented-control
+ *
+ * @module
+ */
+import { GwElement, css, h, setAttribute } from "./element.js";
+import { base, createIcon } from "./styles.js";
+
+export interface Segment {
+  readonly value: string;
+  readonly label: string;
+  /** SVG path data for an icon beside, or instead of, the label. */
+  readonly icon?: string;
+}
+
+/**
+ * Picks one of a few options, as a row of native radio buttons, so arrow
+ * keys move between them and a form submits the choice. Fires `change`.
+ *
+ * Options can carry icons, as Home Assistant's toggles do. `labels` decides
+ * whether their text shows: `show` (the default), `hide` (icons only, with
+ * the text as a tooltip and accessible name) or `auto`, which shows the text
+ * on wide screens and only the icons on narrow ones.
+ *
+ * @element gw-segmented
+ * @summary Picks one of a few options, as a row of radio buttons.
+ *
+ * @attr {string} label - The group's accessible name.
+ * @attr {string} name - The form field name. Defaults to a unique name.
+ * @attr {string} value - The chosen option's value.
+ * @attr {"show"|"hide"|"auto"} labels - Whether option text shows beside icons. Defaults to `show`.
+ * @attr {Segment[]} options - The options, as JSON.
+ *
+ * @csspart indicator - The pill that slides to the chosen option.
+ *
+ * @fires change - When the chosen option changes.
+ */
+export class GwSegmented extends GwElement {
+  static override properties = {
+    label: {},
+    name: {},
+    value: { reflect: true },
+    labels: { reflect: true },
+    options: { type: "json" },
+  } as const;
+
+  static override styles = [
+    base,
+    css`
+      :host {
+        display: inline-block;
+      }
+
+      /* A pill track with the picked option as a pill inside, as Home
+         Assistant's toggles are */
+      fieldset {
+        display: inline-flex;
+        gap: 2px;
+        padding: 3px;
+        margin: 0;
+        background: var(--gw-color-surface-lower);
+        border: max(var(--gw-border-width), 1px) solid
+          var(--gw-color-border-normal);
+        border-radius: var(--gw-radius-pill);
+      }
+
+      legend {
+        position: absolute;
+        width: 1px;
+        height: 1px;
+        overflow: hidden;
+        clip-path: inset(50%);
+        white-space: nowrap;
+      }
+
+      label {
+        position: relative;
+        display: inline-flex;
+        gap: var(--gw-space-2);
+        align-items: center;
+        box-sizing: border-box;
+        /* 32px options in a 40px track, matching fields and buttons */
+        height: 2rem;
+        padding: 0 var(--gw-space-3);
+        font-size: var(--gw-font-size-s);
+        color: var(--gw-color-text-primary);
+        cursor: pointer;
+        background: transparent;
+        border-radius: var(--gw-radius-pill);
+        transition: background-color var(--gw-motion-fast)
+          var(--gw-motion-easing);
+        --gw-icon-size: 1.125rem;
+      }
+
+      :host([labels="hide"]) label.has-icon {
+        padding-inline: var(--gw-space-2);
+      }
+
+      :host([labels="hide"]) label.has-icon .text {
+        position: absolute;
+        width: 1px;
+        height: 1px;
+        overflow: hidden;
+        clip-path: inset(50%);
+        white-space: nowrap;
+      }
+
+      @media (width < 40rem) {
+        :host([labels="auto"]) label.has-icon {
+          padding-inline: var(--gw-space-2);
+        }
+
+        :host([labels="auto"]) label.has-icon .text {
+          position: absolute;
+          width: 1px;
+          height: 1px;
+          overflow: hidden;
+          clip-path: inset(50%);
+          white-space: nowrap;
+        }
+      }
+
+      label:hover {
+        background: var(--gw-color-fill-neutral-hovered);
+      }
+
+      input {
+        position: absolute;
+        inset: 0;
+        margin: 0;
+        cursor: pointer;
+        opacity: 0;
+      }
+
+      /* The picked pill is one element that slides between options, under
+         their text, so the choice moves rather than jumps */
+      fieldset {
+        position: relative;
+        isolation: isolate;
+      }
+
+      .indicator {
+        position: absolute;
+        inset-block-start: 0;
+        inset-inline-start: 0;
+        z-index: -1;
+        background: var(--gw-color-fill-accent-resting);
+        border-radius: var(--gw-radius-pill);
+        box-shadow: var(--gw-shadow-s);
+        opacity: 0;
+      }
+
+      .indicator.placed {
+        opacity: 1;
+      }
+
+      .indicator.moving {
+        transition:
+          translate var(--gw-motion-normal) var(--gw-motion-easing),
+          width var(--gw-motion-normal) var(--gw-motion-easing),
+          height var(--gw-motion-normal) var(--gw-motion-easing);
+      }
+
+      label {
+        transition:
+          background-color var(--gw-motion-fast) var(--gw-motion-easing),
+          color var(--gw-motion-normal) var(--gw-motion-easing);
+      }
+
+      label:has(input:checked),
+      label:has(input:checked):hover {
+        color: var(--gw-color-on-accent);
+        background: transparent;
+      }
+
+      label:has(input:focus-visible) {
+        outline: var(--gw-focus-width) solid var(--gw-color-focus);
+        /* Inset, so the ring sits inside the track rather than on its border */
+        outline-offset: calc(var(--gw-focus-width) * -1);
+      }
+    `,
+  ];
+
+  declare label: string;
+  declare name: string;
+  declare value: string;
+  declare labels: "show" | "hide" | "auto";
+  declare options: readonly Segment[];
+
+  constructor() {
+    super();
+    this.label = "";
+    this.name = `gw-segmented-${Math.random().toString(36).slice(2)}`;
+    this.value = "";
+    this.labels = "show";
+    this.options = [];
+  }
+
+  readonly #legend = h("legend");
+
+  readonly #indicator = h("span", { class: "indicator", part: "indicator" });
+
+  readonly #fieldset = h("fieldset", {}, this.#legend, this.#indicator);
+
+  #segments: {
+    label: HTMLLabelElement;
+    input: HTMLInputElement;
+    option: Segment;
+  }[] = [];
+
+  readonly #resize = new ResizeObserver(() => this.#place(false));
+
+  #pick(value: string) {
+    this.value = value;
+    this.dispatchEvent(new Event("change", { bubbles: true, composed: true }));
+  }
+
+  /** Puts the pill under the picked option, sliding there unless it's the first placing. */
+  #place(animate: boolean) {
+    const indicator = this.#indicator;
+
+    const picked = this.#segments.find(({ input }) => input.checked)?.label;
+
+    if (picked === undefined) {
+      indicator.classList.remove("placed");
+
+      return;
+    }
+
+    indicator.classList.toggle(
+      "moving",
+      animate && indicator.classList.contains("placed"),
+    );
+    indicator.style.translate = `${picked.offsetLeft}px ${picked.offsetTop}px`;
+    indicator.style.width = `${picked.offsetWidth}px`;
+    indicator.style.height = `${picked.offsetHeight}px`;
+    indicator.classList.add("placed");
+  }
+
+  override connectedCallback() {
+    super.connectedCallback();
+    this.#resize.observe(this);
+  }
+
+  override disconnectedCallback() {
+    super.disconnectedCallback();
+    this.#resize.disconnect();
+  }
+
+  protected override create(root: ShadowRoot) {
+    root.append(this.#fieldset);
+  }
+
+  protected override update(changed: ReadonlySet<string>) {
+    this.#legend.textContent = this.label;
+
+    if (changed.has("options")) {
+      const options = Array.isArray(this.options) ? this.options : [];
+
+      for (const { label } of this.#segments) label.remove();
+
+      this.#segments = options.map((option) => {
+        const input = h("input", { type: "radio", value: option.value });
+
+        input.addEventListener("change", () => this.#pick(option.value));
+
+        const label = h(
+          "label",
+          { class: option.icon ? "has-icon" : null },
+          input,
+          option.icon ? createIcon(option.icon) : null,
+          h("span", { class: "text" }, option.label),
+        );
+
+        return { label, input, option };
+      });
+      this.#fieldset.append(...this.#segments.map(({ label }) => label));
+    }
+
+    for (const { label, input, option } of this.#segments) {
+      input.name = this.name;
+      input.checked = option.value === this.value;
+      setAttribute(
+        label,
+        "title",
+        option.icon && this.labels !== "show" ? option.label : null,
+      );
+    }
+
+    this.#place(true);
+  }
+}
+
+GwSegmented.define("gw-segmented");
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "gw-segmented": GwSegmented;
+  }
+}

package/src/gw-select.ts

@@ -0,0 +1,361 @@
+/**
+ * `gw-select`: a labeled picker with search, a bottom sheet on phones.
+ * Docs: https://groundwork.timmo.dev/components/inputs/#select
+ *
+ * @module
+ */
+import { h, setAttribute } from "./element.js";
+import { FieldInfo } from "./field-info.js";
+import { LightElement, fieldId } from "./fields.js";
+import "./gw-option-list.js";
+import type { OptionItem } from "./gw-option-list.js";
+import { createIcon, setIconPath } from "./styles.js";
+
+/** @deprecated Use `OptionItem`, which also takes an icon, description and group. */
+export type SelectOption = OptionItem;
+
+/** An option being read from markup, filled in field by field. */
+type DraftOption = { -readonly [Key in keyof OptionItem]: OptionItem[Key] };
+
+const gap = 6;
+
+/** Below this width the list is a bottom sheet. */
+const sheetBelow = 600;
+
+/** From this many options a search field shows by default. */
+const searchFrom = 7;
+
+// MDI's chevron-down
+const chevronIcon =
+  "M7.41,8.58L12,13.17L16.59,8.58L18,10L12,16L6,10L7.41,8.58Z";
+
+/**
+ * A labeled select whose list opens under it, after Home Assistant's
+ * pickers. Long lists get a search field, focused as the list opens, and
+ * only the options in view are rendered. Move with the arrow keys and pick
+ * with Enter. Below 600px wide the list is a bottom sheet.
+ *
+ * Pass `options`, or write `<option>` children (in `<optgroup>`s for
+ * groups, with `data-icon` and `data-description`), which it reads once when
+ * it first connects. A hidden input carries the value in forms, and it fires
+ * `change` when the value changes.
+ *
+ * @element gw-select
+ * @summary A labeled picker with search, a bottom sheet on phones.
+ *
+ * @attr {string} label - The field's label.
+ * @attr {string} name - The form field name.
+ * @attr {string} value - The chosen option's value.
+ * @attr {string} hint - One line of help under the field.
+ * @attr {string} info - Longer help, opened from an (i) button by the label.
+ * @attr {string} placeholder - What the trigger shows with nothing chosen. Defaults to `Choose`.
+ * @attr {"auto"|"always"|"never"} search - Whether the list has a search field; `auto` adds one from 7 options. Defaults to `auto`.
+ * @attr {boolean} disabled - Disables the field.
+ * @attr {boolean} open - Whether the list shows.
+ * @attr {OptionItem[]} options - The options, as JSON.
+ * @attr {boolean} label-hidden - Hides the label but keeps it for assistive technology.
+ * @attr {boolean} inline-label - Shows the label inside the trigger, before the value, for toolbars and filters.
+ *
+ * @fires change - When the value changes.
+ */
+export class GwSelect extends LightElement {
+  static override properties = {
+    label: {},
+    name: {},
+    value: {},
+    hint: {},
+    info: {},
+    placeholder: {},
+    search: {},
+    disabled: { type: "boolean" },
+    open: { type: "boolean", reflect: true },
+    options: { type: "json" },
+    labelHidden: { type: "boolean", attribute: "label-hidden" },
+    inlineLabel: { type: "boolean", attribute: "inline-label", reflect: true },
+  } as const;
+
+  declare label: string;
+  declare name: string;
+  declare value: string;
+  declare hint: string;
+  /** Longer help, opened from an (i) button by the label. */
+  declare info: string;
+  declare placeholder: string;
+  /** `auto` shows a search field from seven options; `always` or `never` overrides that. */
+  declare search: "auto" | "always" | "never";
+  declare disabled: boolean;
+  declare open: boolean;
+  declare options: readonly OptionItem[];
+  declare labelHidden: boolean;
+  declare inlineLabel: boolean;
+
+  readonly #id = fieldId();
+
+  readonly #label = h("label", { id: `${this.#id}-label` });
+
+  readonly #info = new FieldInfo(this.#label);
+
+  readonly #icon = createIcon("");
+
+  // The trigger is already labelled by the real label, so this copy is hidden
+  // from assistive technology
+  readonly #inline = h("span", {
+    class: "gw-select-inline-label",
+    "aria-hidden": "true",
+  });
+
+  readonly #text = h("span", { class: "gw-select-value" });
+
+  readonly #trigger = h(
+    "button",
+    {
+      type: "button",
+      class: "gw-select-trigger",
+      id: this.#id,
+      "aria-haspopup": "listbox",
+      "aria-labelledby": `${this.#id}-label ${this.#id}`,
+    },
+    this.#icon,
+    this.#inline,
+    // Keeps the visible text "Theme Base" rather than "ThemeBase", matching
+    // the accessible name
+    " ",
+    this.#text,
+    createIcon(chevronIcon),
+  );
+
+  readonly #input = h("input", { type: "hidden" });
+
+  readonly #hint = h("p", { class: "gw-hint", id: `${this.#id}-hint` });
+
+  readonly #list = h("gw-option-list");
+
+  readonly #popup = h(
+    "div",
+    { class: "gw-select-popup", popover: "manual" },
+    this.#list,
+  );
+
+  constructor() {
+    super();
+    this.label = "";
+    this.name = "";
+    this.value = "";
+    this.hint = "";
+    this.info = "";
+    this.placeholder = "Choose";
+    this.search = "auto";
+    this.disabled = false;
+    this.open = false;
+    this.options = [];
+    this.labelHidden = false;
+    this.inlineLabel = false;
+  }
+
+  /** Opens the list, such as from a keyboard shortcut. */
+  show() {
+    if (this.disabled || this.#popup.matches(":popover-open")) return;
+
+    this.#popup.dataset.placement =
+      window.innerWidth < sheetBelow ? "sheet" : "below";
+    this.#popup.showPopover();
+  }
+
+  close() {
+    if (this.#popup.matches(":popover-open")) this.#popup.hidePopover();
+  }
+
+  #readChildren() {
+    const children = [...this.querySelectorAll("option")];
+
+    if (this.options.length === 0 && children.length > 0) {
+      this.options = children.map((option) => {
+        const group = option.parentElement;
+
+        const item: DraftOption = {
+          value: option.value,
+          label: option.textContent.trim(),
+        };
+
+        if (option.dataset.icon !== undefined) item.icon = option.dataset.icon;
+
+        if (option.dataset.description !== undefined) {
+          item.description = option.dataset.description;
+        }
+
+        if (group instanceof HTMLOptGroupElement) item.group = group.label;
+
+        return item;
+      });
+
+      const picked = children.find((option) => option.selected);
+
+      if (this.value === "" && picked !== undefined) this.value = picked.value;
+    }
+
+    for (const element of this.querySelectorAll("option, optgroup")) {
+      element.remove();
+    }
+  }
+
+  readonly #position = () => {
+    const popup = this.#popup;
+
+    if (popup.dataset.placement === "sheet") {
+      popup.style.top = "";
+      popup.style.left = "";
+      popup.style.width = "";
+
+      return;
+    }
+
+    const rect = this.#trigger.getBoundingClientRect();
+    const width = Math.max(rect.width, 224);
+
+    popup.style.width = `${Math.min(width, window.innerWidth - 2 * gap)}px`;
+
+    const below = window.innerHeight - rect.bottom - gap;
+    const fitsBelow = below >= popup.offsetHeight || below >= rect.top;
+
+    popup.dataset.placement = fitsBelow ? "below" : "above";
+    popup.style.top = `${fitsBelow ? rect.bottom + gap : Math.max(gap, rect.top - gap - popup.offsetHeight)}px`;
+    popup.style.left = `${Math.min(Math.max(gap, rect.left), window.innerWidth - popup.offsetWidth - gap)}px`;
+  };
+
+  readonly #onOutside = (event: PointerEvent) => {
+    if (!event.composedPath().includes(this)) this.close();
+  };
+
+  readonly #onToggle = (event: ToggleEvent) => {
+    this.open = event.newState === "open";
+
+    if (this.open) {
+      this.#position();
+      this.#list.reset();
+      window.addEventListener("resize", this.#position);
+      window.addEventListener("scroll", this.#position, true);
+      document.addEventListener("pointerdown", this.#onOutside, true);
+
+      return;
+    }
+
+    this.#stopListening();
+  };
+
+  #stopListening() {
+    window.removeEventListener("resize", this.#position);
+    window.removeEventListener("scroll", this.#position, true);
+    document.removeEventListener("pointerdown", this.#onOutside, true);
+  }
+
+  override disconnectedCallback() {
+    this.#stopListening();
+    super.disconnectedCallback();
+  }
+
+  protected override create(root: HTMLElement) {
+    this.#readChildren();
+
+    this.#label.addEventListener("click", () => {
+      this.#trigger.focus();
+    });
+    this.#trigger.addEventListener("click", () => {
+      if (this.open) {
+        this.close();
+      } else {
+        this.show();
+      }
+    });
+    this.#trigger.addEventListener("keydown", (event) => {
+      if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+        event.preventDefault();
+        this.show();
+      }
+    });
+    this.#popup.addEventListener("toggle", this.#onToggle);
+    this.#popup.addEventListener("keydown", (event) => {
+      if (event.key === "Escape") {
+        event.preventDefault();
+        event.stopPropagation();
+        this.close();
+        this.#trigger.focus();
+      } else if (event.key === "Tab") {
+        this.close();
+        this.#trigger.focus();
+      }
+    });
+    this.#list.addEventListener("pick", (event) => {
+      event.stopPropagation();
+
+      const value =
+        event instanceof CustomEvent &&
+        event.detail !== null &&
+        "value" in event.detail
+          ? String(event.detail.value)
+          : "";
+
+      this.close();
+      this.#trigger.focus();
+
+      if (value !== this.value) {
+        this.value = value;
+        this.dispatchEvent(new Event("change", { bubbles: true }));
+      }
+    });
+
+    root.append(
+      this.#info.heading,
+      this.#trigger,
+      this.#input,
+      this.#hint,
+      this.#popup,
+    );
+  }
+
+  protected override update() {
+    const options = Array.isArray(this.options) ? this.options : [];
+    const selected = options.find((option) => option.value === this.value);
+
+    this.#label.textContent = this.label;
+    this.#info.update(this.label, this.info);
+    this.#info.heading.classList.toggle(
+      "gw-visually-hidden",
+      this.labelHidden || this.inlineLabel,
+    );
+    this.#inline.textContent = this.label;
+    this.#inline.hidden = !this.inlineLabel;
+    this.#text.textContent = selected?.label ?? this.placeholder;
+    this.#text.toggleAttribute("data-placeholder", selected === undefined);
+    setIconPath(this.#icon, selected?.icon ?? "");
+    this.#icon.toggleAttribute("hidden", selected?.icon === undefined);
+
+    const trigger = this.#trigger;
+
+    trigger.disabled = this.disabled;
+    setAttribute(trigger, "aria-expanded", this.open ? "true" : "false");
+    setAttribute(trigger, "aria-describedby", this.hint ? this.#hint.id : null);
+
+    setAttribute(this.#input, "name", this.name || null);
+    this.#input.value = this.value;
+
+    const list = this.#list;
+
+    list.options = options;
+    list.value = this.value;
+    list.label = this.label;
+    list.search =
+      this.search === "always" ||
+      (this.search !== "never" && options.length >= searchFrom);
+
+    this.#hint.textContent = this.hint;
+    this.#hint.hidden = !this.hint;
+  }
+}
+
+GwSelect.define("gw-select");
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "gw-select": GwSelect;
+  }
+}