@timmo001/groundwork-ui 0.3.1 → 0.4.1

package/src/gw-select.ts

@@ -36,9 +36,14 @@ const chevronIcon =
  * 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.
+ * groups, with `data-icon`, `data-swatch` 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.
+ *
+ * With `multiple` it picks several: each pick toggles an option in `values`
+ * and the list stays open, the trigger shows the first choice and how many
+ * more, and a Clear button under the list empties it. A hidden input per
+ * value carries them in forms.
  *
  * @element gw-select
  * @summary A labeled picker with search, a bottom sheet on phones.
@@ -46,6 +51,8 @@ const chevronIcon =
  * @attr {string} label - The field's label.
  * @attr {string} name - The form field name.
  * @attr {string} value - The chosen option's value.
+ * @attr {boolean} multiple - Picks several options, kept in `values`.
+ * @attr {string[]} values - The chosen options' values with `multiple`, as JSON.
  * @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`.
@@ -56,13 +63,15 @@ const chevronIcon =
  * @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.
+ * @fires {Event} change - When the value, or `values` with `multiple`, changes.
  */
 export class GwSelect extends LightElement {
   static override properties = {
     label: {},
     name: {},
     value: {},
+    multiple: { type: "boolean", reflect: true },
+    values: { type: "json" },
     hint: {},
     info: {},
     placeholder: {},
@@ -77,6 +86,8 @@ export class GwSelect extends LightElement {
   declare label: string;
   declare name: string;
   declare value: string;
+  declare multiple: boolean;
+  declare values: readonly string[];
   declare hint: string;
   /** Longer help, opened from an (i) button by the label. */
   declare info: string;
@@ -126,14 +137,23 @@ export class GwSelect extends LightElement {
 
   readonly #input = h("input", { type: "hidden" });
 
+  readonly #inputs = h("span", { hidden: true });
+
   readonly #hint = h("p", { class: "gw-hint", id: `${this.#id}-hint` });
 
   readonly #list = h("gw-option-list");
 
+  readonly #clear = h(
+    "button",
+    { type: "button", class: "gw-select-clear" },
+    "Clear",
+  );
+
   readonly #popup = h(
     "div",
     { class: "gw-select-popup", popover: "manual" },
     this.#list,
+    this.#clear,
   );
 
   constructor() {
@@ -141,6 +161,8 @@ export class GwSelect extends LightElement {
     this.label = "";
     this.name = "";
     this.value = "";
+    this.multiple = false;
+    this.values = [];
     this.hint = "";
     this.info = "";
     this.placeholder = "Choose";
@@ -179,6 +201,10 @@ export class GwSelect extends LightElement {
 
         if (option.dataset.icon !== undefined) item.icon = option.dataset.icon;
 
+        if (option.dataset.swatch !== undefined) {
+          item.swatch = option.dataset.swatch;
+        }
+
         if (option.dataset.description !== undefined) {
           item.description = option.dataset.description;
         }
@@ -188,9 +214,15 @@ export class GwSelect extends LightElement {
         return item;
       });
 
-      const picked = children.find((option) => option.selected);
+      const picked = children.filter((option) => option.selected);
 
-      if (this.value === "" && picked !== undefined) this.value = picked.value;
+      if (this.multiple) {
+        if (this.values.length === 0 && picked.length > 0) {
+          this.values = picked.map((option) => option.value);
+        }
+      } else if (this.value === "" && picked[0] !== undefined) {
+        this.value = picked[0].value;
+      }
     }
 
     for (const element of this.querySelectorAll("option, optgroup")) {
@@ -294,6 +326,17 @@ export class GwSelect extends LightElement {
           ? String(event.detail.value)
           : "";
 
+      if (this.multiple) {
+        const chosen = Array.isArray(this.values) ? this.values : [];
+
+        this.values = chosen.includes(value)
+          ? chosen.filter((item) => item !== value)
+          : [...chosen, value];
+        this.dispatchEvent(new Event("change", { bubbles: true }));
+
+        return;
+      }
+
       this.close();
       this.#trigger.focus();
 
@@ -302,19 +345,44 @@ export class GwSelect extends LightElement {
         this.dispatchEvent(new Event("change", { bubbles: true }));
       }
     });
+    this.#clear.addEventListener("click", () => {
+      this.values = [];
+      this.close();
+      this.#trigger.focus();
+      this.dispatchEvent(new Event("change", { bubbles: true }));
+    });
 
     root.append(
       this.#info.heading,
       this.#trigger,
       this.#input,
+      this.#inputs,
       this.#hint,
       this.#popup,
     );
   }
 
+  /** What the trigger says: the choice, or with `multiple` the first and how many more. */
+  #summary(options: readonly OptionItem[]) {
+    if (!this.multiple) {
+      return options.find((option) => option.value === this.value);
+    }
+
+    const values = Array.isArray(this.values) ? this.values : [];
+    const chosen = options.filter((option) => values.includes(option.value));
+    const [first] = chosen;
+
+    if (first === undefined) return undefined;
+
+    return chosen.length === 1
+      ? first
+      : { ...first, label: `${first.label} +${chosen.length - 1}` };
+  }
+
   protected override update() {
     const options = Array.isArray(this.options) ? this.options : [];
-    const selected = options.find((option) => option.value === this.value);
+    const selected = this.#summary(options);
+    const values = Array.isArray(this.values) ? this.values : [];
 
     this.#label.textContent = this.label;
     this.#info.update(this.label, this.info);
@@ -335,13 +403,23 @@ export class GwSelect extends LightElement {
     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;
+    setAttribute(this.#input, "name", this.multiple ? null : this.name || null);
+    this.#input.value = this.multiple ? "" : this.value;
+    this.#inputs.replaceChildren(
+      ...(this.multiple && this.name
+        ? values.map((value) =>
+            h("input", { type: "hidden", name: this.name, value }),
+          )
+        : []),
+    );
+    this.#clear.hidden = !this.multiple || values.length === 0;
 
     const list = this.#list;
 
     list.options = options;
     list.value = this.value;
+    list.multiple = this.multiple;
+    list.values = values;
     list.label = this.label;
     list.search =
       this.search === "always" ||

package/src/gw-theme-picker.ts

@@ -0,0 +1,200 @@
+/**
+ * `gw-theme-picker`: a button opening the page's mode, theme and import.
+ * Docs: https://groundwork.timmo.dev/components/actions/#theme-picker
+ *
+ * @module
+ */
+import { GwElement, css, h } from "./element.js";
+import "./gw-button.js";
+import type { OptionItem } from "./gw-option-list.js";
+import "./gw-popover.js";
+import "./gw-segmented.js";
+import "./gw-select.js";
+import { base } from "./styles.js";
+
+// MDI's palette
+const paletteIcon =
+  "M17.5,12A1.5,1.5 0 0,1 16,10.5A1.5,1.5 0 0,1 17.5,9A1.5,1.5 0 0,1 19,10.5A1.5,1.5 0 0,1 17.5,12M14.5,8A1.5,1.5 0 0,1 13,6.5A1.5,1.5 0 0,1 14.5,5A1.5,1.5 0 0,1 16,6.5A1.5,1.5 0 0,1 14.5,8M9.5,8A1.5,1.5 0 0,1 8,6.5A1.5,1.5 0 0,1 9.5,5A1.5,1.5 0 0,1 11,6.5A1.5,1.5 0 0,1 9.5,8M6.5,12A1.5,1.5 0 0,1 5,10.5A1.5,1.5 0 0,1 6.5,9A1.5,1.5 0 0,1 8,10.5A1.5,1.5 0 0,1 6.5,12M12,3A9,9 0 0,0 3,12A9,9 0 0,0 12,21A1.5,1.5 0 0,0 13.5,19.5C13.5,19.11 13.35,18.76 13.11,18.5C12.88,18.23 12.73,17.88 12.73,17.5A1.5,1.5 0 0,1 14.23,16H16A5,5 0 0,0 21,11C21,6.58 16.97,3 12,3Z";
+
+const modes = [
+  { value: "auto", label: "Auto" },
+  { value: "light", label: "Light" },
+  { value: "dark", label: "Dark" },
+  { value: "darker", label: "Darker" },
+] as const;
+
+/**
+ * A palette button for a page's look. It opens a popover with the mode
+ * (auto, light, dark or Darker), the theme, and buttons to import a theme
+ * file (a Groundwork theme's `.json` or an Omarchy `colors.toml`) or reset.
+ *
+ * It only asks: it fires `mode`, `theme`, `import` and `reset`, and the page
+ * applies them and sets `mode`, `theme` and `themes` back. `pageTheme` from
+ * `@timmo001/groundwork-tokens/page` does all of that. Show an import's
+ * result, such as contrast misses, in `status`.
+ *
+ * @element gw-theme-picker
+ * @summary A button opening the page's mode, theme and import.
+ *
+ * @attr {"auto"|"light"|"dark"|"darker"} mode - The mode in use. Defaults to `auto`.
+ * @attr {string} theme - The theme in use, by id.
+ * @attr {OptionItem[]} themes - The themes to offer, as JSON.
+ * @attr {string} status - A line under the controls, such as an import's result.
+ * @attr {string} label - The button's accessible name and the popover's heading. Defaults to `Theme`.
+ *
+ * @fires {CustomEvent<{ mode: string }>} mode - When a mode is picked.
+ * @fires {CustomEvent<{ id: string }>} theme - When a theme is picked.
+ * @fires {CustomEvent<{ text: string, name: string }>} import - When a theme file is chosen, with its text and file name.
+ * @fires {Event} reset - When Reset is pressed.
+ */
+export class GwThemePicker extends GwElement {
+  static override properties = {
+    mode: { reflect: true },
+    theme: { reflect: true },
+    themes: { type: "json" },
+    status: {},
+    label: {},
+  } as const;
+
+  static override styles = [
+    base,
+    css`
+      :host {
+        display: inline-block;
+      }
+
+      .controls {
+        display: flex;
+        flex-direction: column;
+        gap: var(--gw-space-4);
+        margin-block-start: var(--gw-space-2);
+      }
+
+      .status {
+        margin: 0;
+        font-size: var(--gw-font-size-s);
+        color: var(--gw-color-text-secondary);
+      }
+    `,
+  ];
+
+  declare mode: string;
+  declare theme: string;
+  declare themes: readonly OptionItem[];
+  declare status: string;
+  declare label: string;
+
+  readonly #button = h("gw-button", {
+    variant: "neutral",
+    appearance: "plain",
+    icon: paletteIcon,
+    labels: "hide",
+  });
+
+  readonly #mode = h("gw-segmented");
+
+  readonly #theme = h("gw-select", { label: "Theme" });
+
+  readonly #status = h("p", { class: "status", role: "status" });
+
+  readonly #file = h("input", {
+    type: "file",
+    accept: ".json,.toml,application/json",
+    hidden: true,
+  });
+
+  readonly #popover = h(
+    "gw-popover",
+    {},
+    h("div", { class: "controls" }, this.#mode, this.#theme, this.#status),
+    h(
+      "gw-button",
+      {
+        slot: "actions",
+        variant: "neutral",
+        appearance: "plain",
+        class: "reset",
+      },
+      "Reset",
+    ),
+    h(
+      "gw-button",
+      { slot: "actions", appearance: "outlined", class: "import" },
+      "Import",
+    ),
+  );
+
+  constructor() {
+    super();
+    this.mode = "auto";
+    this.theme = "";
+    this.themes = [];
+    this.status = "";
+    this.label = "Theme";
+  }
+
+  /** Opens the popover under the button. */
+  show() {
+    this.#popover.show(this.#button);
+  }
+
+  #detail<Detail>(type: string, detail: Detail) {
+    return new CustomEvent(type, { detail, bubbles: true, composed: true });
+  }
+
+  protected override create(root: ShadowRoot) {
+    this.#mode.options = modes;
+    this.#button.addEventListener("click", () => {
+      this.show();
+    });
+    this.#mode.addEventListener("change", (event) => {
+      event.stopPropagation();
+      this.mode = this.#mode.value;
+      this.dispatchEvent(this.#detail("mode", { mode: this.mode }));
+    });
+    this.#theme.addEventListener("change", (event) => {
+      event.stopPropagation();
+      this.theme = this.#theme.value;
+      this.dispatchEvent(this.#detail("theme", { id: this.theme }));
+    });
+    this.#popover.querySelector(".import")?.addEventListener("click", () => {
+      this.#file.click();
+    });
+    this.#popover.querySelector(".reset")?.addEventListener("click", () => {
+      this.dispatchEvent(new Event("reset", { bubbles: true, composed: true }));
+    });
+    this.#file.addEventListener("change", async () => {
+      const file = this.#file.files?.[0];
+
+      this.#file.value = "";
+
+      if (file === undefined) return;
+
+      const text = await file.text();
+
+      this.dispatchEvent(this.#detail("import", { text, name: file.name }));
+    });
+
+    root.append(this.#button, this.#popover, this.#file);
+  }
+
+  protected override update() {
+    this.#button.label = this.label;
+    this.#button.textContent = this.label;
+    this.#popover.heading = this.label;
+    this.#mode.label = "Mode";
+    this.#mode.value = this.mode;
+    this.#theme.options = Array.isArray(this.themes) ? this.themes : [];
+    this.#theme.value = this.theme;
+    this.#status.textContent = this.status;
+    this.#status.hidden = !this.status;
+  }
+}
+
+GwThemePicker.define("gw-theme-picker");
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "gw-theme-picker": GwThemePicker;
+  }
+}

package/src/index.ts

@@ -15,8 +15,12 @@ export * from "./fields.js";
 
 export * from "./layout.js";
 
+export * from "./on.js";
+
 export * from "./gw-alert.js";
 
+export * from "./gw-app-bar.js";
+
 export * from "./gw-badge.js";
 
 export * from "./gw-banner.js";
@@ -73,4 +77,6 @@ export * from "./gw-skeleton.js";
 
 export * from "./gw-spinner.js";
 
+export * from "./gw-theme-picker.js";
+
 export * from "./gw-toast.js";

package/src/on.ts

@@ -0,0 +1,52 @@
+/**
+ * `on()`: listens for a `gw-` element's own events, typed from the
+ * generated `GwEventMap`, so a handler gets `CustomEvent<{ value: string }>`
+ * for `pick` with no cast.
+ * Docs: https://groundwork.timmo.dev/components/#using-with-lit
+ *
+ * @module
+ */
+import type { GwEventMap } from "./events.js";
+
+export type { GwEventMap } from "./events.js";
+
+type EventTag = keyof GwEventMap;
+
+/** A `gw-` element that fires events of its own. */
+export type GwEventTarget = HTMLElementTagNameMap[EventTag];
+
+/** The events an element fires, found from the tag its class is defined for. */
+export type GwEventsOf<E extends GwEventTarget> = {
+  [T in EventTag]: E extends HTMLElementTagNameMap[T] ? GwEventMap[T] : never;
+}[EventTag];
+
+/**
+ * A handler for one event. Declared as a method so it's checked bivariantly
+ * and can be handed to `addEventListener`, which only knows it as an `Event`.
+ */
+type Listener<T extends Event> = {
+  handle(event: T): void;
+}["handle"];
+
+/**
+ * Adds a listener for one of the element's own events, typed from its
+ * `@fires` docs, and returns a function that removes it.
+ *
+ * @example
+ * on(menu, "pick", (event) => open(event.detail.value));
+ */
+export function on<
+  E extends GwEventTarget,
+  K extends keyof GwEventsOf<E> & string,
+>(
+  element: E,
+  type: K,
+  listener: Listener<GwEventsOf<E>[K] & Event>,
+  options?: AddEventListenerOptions,
+): () => void {
+  const handler: Listener<Event> = listener;
+
+  element.addEventListener(type, handler, options);
+
+  return () => element.removeEventListener(type, handler, options);
+}