@timmo001/groundwork-ui 0.5.0 → 0.6.0

package/src/gw-option-list.ts

@@ -81,6 +81,13 @@ let lastList = 0;
  * @attr {boolean} search - Shows a search field above the list.
  * @attr {string} placeholder - The search placeholder. Defaults to `Search`.
  *
+ * @csspart search - The search field's row.
+ * @csspart listbox - The scrolling list.
+ * @csspart option - Each option.
+ * @csspart group - Each group heading.
+ * @csspart description - An option's second line.
+ * @csspart none - The no matches line.
+ *
  * @cssprop --gw-option-list-height - The list's maximum height. Defaults to `20rem`.
  *
  * @fires {CustomEvent<{ value: string }>} pick - When an option is picked, with its `value` in `detail`.
@@ -273,11 +280,15 @@ export class GwOptionList extends GwElement {
 
   readonly #listbox = h(
     "div",
-    { role: "listbox", tabindex: "-1" },
+    { role: "listbox", part: "listbox", tabindex: "-1" },
     this.#spacer,
   );
 
-  readonly #none = h("div", { class: "none", hidden: true }, "No matches");
+  readonly #none = h(
+    "div",
+    { class: "none", part: "none", hidden: true },
+    "No matches",
+  );
 
   #query = "";
 
@@ -433,7 +444,12 @@ export class GwOptionList extends GwElement {
     });
 
     root.append(
-      h("div", { class: "search" }, createIcon(searchIcon), this.#input),
+      h(
+        "div",
+        { class: "search", part: "search" },
+        createIcon(searchIcon),
+        this.#input,
+      ),
       this.#listbox,
       this.#none,
     );
@@ -585,7 +601,7 @@ export class GwOptionList extends GwElement {
     if (row.kind === "group") {
       const element = h(
         "div",
-        { class: "row group", role: "presentation" },
+        { class: "row group", part: "group", role: "presentation" },
         row.label,
       );
 
@@ -602,6 +618,7 @@ export class GwOptionList extends GwElement {
       "div",
       {
         class: "row",
+        part: "option",
         role: "option",
         id: `${this.#id}-${index}`,
         "data-index": index,
@@ -618,7 +635,11 @@ export class GwOptionList extends GwElement {
         h("span", {}, option.label),
         option.description === undefined
           ? null
-          : h("span", { class: "description" }, option.description),
+          : h(
+              "span",
+              { class: "description", part: "description" },
+              option.description,
+            ),
       ),
       option.swatches === undefined
         ? null

package/src/gw-page-header.ts

@@ -19,6 +19,10 @@ import { base, createIcon, setIconPath } from "./styles.js";
  * @attr {string} icon - SVG path data for the icon tile.
  *
  * @slot actions - The page's controls.
+ *
+ * @csspart tile - The icon tile.
+ * @csspart heading - The title.
+ * @csspart description - The line under the title.
  */
 export class GwPageHeader extends GwElement {
   static override properties = {
@@ -86,11 +90,11 @@ export class GwPageHeader extends GwElement {
 
   readonly #icon = createIcon("");
 
-  readonly #tile = h("span", { class: "tile" }, this.#icon);
+  readonly #tile = h("span", { class: "tile", part: "tile" }, this.#icon);
 
-  readonly #heading = h("h1");
+  readonly #heading = h("h1", { part: "heading" });
 
-  readonly #description = h("p");
+  readonly #description = h("p", { part: "description" });
 
   constructor() {
     super();

package/src/gw-popover.ts

@@ -38,6 +38,11 @@ const sheetBelow = 600;
  * @slot - The content.
  * @slot actions - Buttons; one with a `value` closes it with that value.
  *
+ * @csspart surface - The popover's surface.
+ * @csspart heading - The heading.
+ * @csspart body - The content.
+ * @csspart footer - The actions row.
+ *
  * @cssprop --gw-popover-width - Its width beside a button. Defaults to `20rem`.
  *
  * @fires {Event} close - When it closes; `returnValue` holds the button's value.
@@ -187,7 +192,7 @@ export class GwPopover extends GwElement {
   /** The value of the action that closed it, or "" for Esc or a click outside. */
   returnValue = "";
 
-  readonly #heading = h("h2", { id: "heading" });
+  readonly #heading = h("h2", { id: "heading", part: "heading" });
 
   readonly #closeButton = h(
     "gw-button",
@@ -204,7 +209,12 @@ export class GwPopover extends GwElement {
 
   readonly #popover = h(
     "div",
-    { popover: "manual", tabindex: "-1", "data-placement": "center" },
+    {
+      popover: "manual",
+      tabindex: "-1",
+      "data-placement": "center",
+      part: "surface",
+    },
     h(
       "header",
       {},
@@ -212,11 +222,11 @@ export class GwPopover extends GwElement {
         "div",
         { class: "content" },
         this.#heading,
-        h("div", { class: "body", id: "body" }, h("slot")),
+        h("div", { class: "body", id: "body", part: "body" }, h("slot")),
       ),
       this.#closeButton,
     ),
-    h("footer", {}, h("slot", { name: "actions" })),
+    h("footer", { part: "footer" }, h("slot", { name: "actions" })),
   );
 
   readonly #dismissal = new Dismissal(

package/src/gw-section-title.ts

@@ -17,6 +17,8 @@ import { base } from "./styles.js";
  *
  * @slot - The heading text.
  * @slot actions - Buttons at the end of the row.
+ *
+ * @csspart heading - The heading.
  */
 export class GwSectionTitle extends GwElement {
   static override properties = {
@@ -46,7 +48,7 @@ export class GwSectionTitle extends GwElement {
 
   declare level: number;
 
-  readonly #heading = h("div", { role: "heading" }, h("slot"));
+  readonly #heading = h("div", { role: "heading", part: "heading" }, h("slot"));
 
   constructor() {
     super();

package/src/gw-segmented.ts

@@ -32,6 +32,7 @@ export interface Segment {
  * @attr {"show"|"hide"|"auto"} labels - Whether option text shows beside icons. Defaults to `show`.
  * @attr {Segment[]} options - The options, as JSON.
  *
+ * @csspart option - Each option.
  * @csspart indicator - The pill that slides to the chosen option.
  *
  * @fires {Event} change - When the chosen option changes.
@@ -267,7 +268,7 @@ export class GwSegmented extends GwElement {
 
         const label = h(
           "label",
-          { class: option.icon ? "has-icon" : null },
+          { class: option.icon ? "has-icon" : null, part: "option" },
           input,
           option.icon ? createIcon(option.icon) : null,
           h("span", { class: "text" }, option.label),

package/src/gw-skeleton.ts

@@ -89,6 +89,8 @@ export class GwSkeletonText extends GwSkeleton {
  * @summary A placeholder for a paragraph.
  *
  * @attr {number} lines - How many lines. Defaults to 3.
+ *
+ * @csspart line - Each line.
  */
 export class GwSkeletonLines extends GwElement {
   static override properties = {
@@ -129,7 +131,7 @@ export class GwSkeletonLines extends GwElement {
   protected override update() {
     this.renderRoot.replaceChildren(
       ...Array.from({ length: Math.max(1, this.lines || 1) }, () =>
-        h("gw-skeleton-text"),
+        h("gw-skeleton-text", { part: "line" }),
       ),
     );
   }

package/src/gw-spinner.ts

@@ -15,6 +15,8 @@ import { base } from "./styles.js";
  *
  * @attr {string} label - What's loading, for assistive technology. Defaults to `Loading`.
  *
+ * @csspart ring - The spinning ring.
+ *
  * @cssprop --gw-spinner-size - The ring's size. Defaults to `1.25rem`.
  */
 export class GwSpinner extends GwElement {
@@ -67,7 +69,9 @@ export class GwSpinner extends GwElement {
   }
 
   protected override create(root: ShadowRoot) {
-    root.append(h("span", { class: "ring", role: "status" }, this.#label));
+    root.append(
+      h("span", { class: "ring", part: "ring", role: "status" }, this.#label),
+    );
   }
 
   protected override update() {

package/src/gw-theme-picker.ts

@@ -17,11 +17,22 @@ import { base } from "./styles.js";
 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" },
+// MDI's sunny, moon and night (a moon with stars), for cycle's button. Auto
+// keeps the palette
+const modeIcons = {
+  auto: paletteIcon,
+  light:
+    "M12,7A5,5 0 0,1 17,12A5,5 0 0,1 12,17A5,5 0 0,1 7,12A5,5 0 0,1 12,7M12,9A3,3 0 0,0 9,12A3,3 0 0,0 12,15A3,3 0 0,0 15,12A3,3 0 0,0 12,9M12,2L14.39,5.42C13.65,5.15 12.84,5 12,5C11.16,5 10.35,5.15 9.61,5.42L12,2M3.34,7L7.5,6.65C6.9,7.16 6.36,7.78 5.94,8.5C5.5,9.24 5.25,10 5.11,10.79L3.34,7M3.36,17L5.12,13.23C5.26,14 5.53,14.78 5.95,15.5C6.37,16.24 6.91,16.86 7.5,17.37L3.36,17M20.65,7L18.88,10.79C18.74,10 18.47,9.23 18.05,8.5C17.63,7.78 17.1,7.15 16.5,6.64L20.65,7M20.64,17L16.5,17.36C17.09,16.85 17.62,16.22 18.04,15.5C18.46,14.77 18.73,14 18.87,13.21L20.64,17M12,22L9.59,18.56C10.33,18.83 11.14,19 12,19C12.82,19 13.63,18.83 14.37,18.56L12,22Z",
+  dark: "M2 12A10 10 0 0 0 15 21.54A10 10 0 0 1 15 2.46A10 10 0 0 0 2 12Z",
+  darker:
+    "M17.75,4.09L15.22,6.03L16.13,9.09L13.5,7.28L10.87,9.09L11.78,6.03L9.25,4.09L12.44,4L13.5,1L14.56,4L17.75,4.09M21.25,11L19.61,12.25L20.2,14.23L18.5,13.06L16.8,14.23L17.39,12.25L15.75,11L17.81,10.95L18.5,9L19.19,10.95L21.25,11M18.97,15.95C19.8,15.87 20.69,17.05 20.16,17.8C19.84,18.25 19.5,18.67 19.08,19.07C15.17,23 8.84,23 4.94,19.07C1.03,15.17 1.03,8.83 4.94,4.93C5.34,4.53 5.76,4.17 6.21,3.85C6.96,3.32 8.14,4.21 8.06,5.04C7.79,7.9 8.75,10.87 10.95,13.06C13.14,15.26 16.1,16.22 18.97,15.95M17.33,17.97C14.5,17.81 11.7,16.64 9.53,14.5C7.36,12.31 6.2,9.5 6.04,6.68C3.23,9.82 3.34,14.64 6.35,17.66C9.37,20.67 14.19,20.78 17.33,17.97Z",
+};
+
+const allModes = [
+  { value: "auto", label: "Auto", icon: modeIcons.auto },
+  { value: "light", label: "Light", icon: modeIcons.light },
+  { value: "dark", label: "Dark", icon: modeIcons.dark },
+  { value: "darker", label: "Darker", icon: modeIcons.darker },
 ] as const;
 
 /**
@@ -37,17 +48,28 @@ const modes = [
  * `gallery` swaps the theme select for `gw-theme-gallery`'s cards, which
  * preview each theme in the chosen mode.
  *
+ * `layout` sets how it shows. `popover`, the default, is the palette button
+ * and its popover. `cycle` is one button showing the mode in use, which steps
+ * to the next mode on each press, for an app bar. `inline` lays the controls
+ * out in place, in one wrapping row with Reset and Import, for a footer or a
+ * settings page; set `justify-content` on it to align the row. `modes` picks which modes it offers, such as `light dark` without
+ * Auto.
+ *
  * @element gw-theme-picker
  * @summary A button opening the page's mode, theme and import.
  *
+ * @attr {"popover"|"cycle"|"inline"} layout - How it shows: a button and popover, a button cycling the modes, or the controls in place. Defaults to `popover`.
+ * @attr {string} modes - The modes to offer, in order and separated by spaces. Defaults to `auto light dark darker`.
  * @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. The select hides with fewer than two. With `gallery`, a `group` gathers a family's themes.
  * @attr {boolean} gallery - Shows the themes as preview cards rather than a select.
  * @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`.
+ * @attr {string} label - The button's accessible name and the popover's heading. Defaults to `Theme`. With `cycle`, the button's name also gives the mode in use.
  *
  * @csspart gallery - The theme gallery, with `gallery`.
+ * @csspart controls - The mode, theme and status.
+ * @csspart actions - Reset and Import, with `inline`.
  *
  * @fires {CustomEvent<{ mode: string }>} mode - When a mode is picked.
  * @fires {CustomEvent<{ id: string }>} theme - When a theme is picked.
@@ -62,6 +84,8 @@ export class GwThemePicker extends GwElement {
     gallery: { type: "boolean", reflect: true },
     status: {},
     label: {},
+    layout: { reflect: true },
+    modes: {},
   } as const;
 
   static override styles = [
@@ -95,6 +119,28 @@ export class GwThemePicker extends GwElement {
         font-size: var(--gw-font-size-s);
         color: var(--gw-color-text-secondary);
       }
+
+      /* One wrapping row: the controls, then Reset and Import. The host is
+         the flex container, so a page can set its justify-content */
+      :host([layout="inline"]) {
+        display: flex;
+        flex-wrap: wrap;
+        gap: var(--gw-space-4);
+        align-items: center;
+      }
+
+      :host([layout="inline"]) .controls {
+        flex-flow: row wrap;
+        align-items: center;
+        margin-block-start: 0;
+      }
+
+      .actions {
+        display: flex;
+        flex-wrap: wrap;
+        gap: var(--gw-space-2);
+        align-items: center;
+      }
     `,
   ];
 
@@ -104,6 +150,10 @@ export class GwThemePicker extends GwElement {
   declare gallery: boolean;
   declare status: string;
   declare label: string;
+  /** How it shows: a button and popover, a button cycling the modes, or the controls in place. */
+  declare layout: "popover" | "cycle" | "inline";
+  /** The modes to offer, in order and separated by spaces. */
+  declare modes: string;
 
   readonly #button = h("gw-button", {
     variant: "neutral",
@@ -129,34 +179,27 @@ export class GwThemePicker extends GwElement {
     hidden: true,
   });
 
-  readonly #popover = h(
-    "gw-popover",
-    {},
-    h(
-      "div",
-      { class: "controls" },
-      this.#mode,
-      this.#theme,
-      this.#gallery,
-      this.#status,
-    ),
-    h(
-      "gw-button",
-      {
-        slot: "actions",
-        variant: "neutral",
-        appearance: "plain",
-        class: "reset",
-      },
-      "Reset",
-    ),
-    h(
-      "gw-button",
-      { slot: "actions", appearance: "outlined", class: "import" },
-      "Import",
-    ),
+  readonly #controls = h(
+    "div",
+    { class: "controls", part: "controls" },
+    this.#mode,
+    this.#theme,
+    this.#gallery,
+    this.#status,
+  );
+
+  readonly #reset = h(
+    "gw-button",
+    { variant: "neutral", appearance: "plain" },
+    "Reset",
   );
 
+  readonly #import = h("gw-button", { appearance: "outlined" }, "Import");
+
+  readonly #popover = h("gw-popover");
+
+  readonly #actions = h("div", { class: "actions", part: "actions" });
+
   constructor() {
     super();
     this.mode = "auto";
@@ -165,22 +208,65 @@ export class GwThemePicker extends GwElement {
     this.gallery = false;
     this.status = "";
     this.label = "Theme";
+    this.layout = "popover";
+    this.modes = "auto light dark darker";
   }
 
-  /** Opens the popover under the button. */
+  /** The modes on offer, in the order `modes` gives them. */
+  #offered() {
+    const wanted = String(this.modes).split(/\s+/);
+    const offered = allModes.filter(({ value }) => wanted.includes(value));
+
+    return offered.length > 0 ? offered : allModes;
+  }
+
+  /** Opens the popover under the button, or with `cycle`, steps to the next mode. */
   show() {
+    if (this.layout === "inline") return;
+
+    if (this.layout === "cycle") {
+      const offered = this.#offered();
+      const at = offered.findIndex(({ value }) => value === this.mode);
+      const next = offered[(at + 1) % offered.length];
+
+      if (next !== undefined) {
+        this.mode = next.value;
+        this.dispatchEvent(this.#detail("mode", { mode: this.mode }));
+      }
+
+      return;
+    }
+
     this.#popover.show(this.#button);
 
     // A custom theme's CSS may have changed since the cards were drawn
     if (this.gallery) this.#gallery.refresh();
   }
 
+  /** Puts the controls and their buttons in the popover, or in place for `inline`. */
+  #place(root: ShadowRoot) {
+    const inline = this.layout === "inline";
+
+    this.#reset.slot = inline ? "" : "actions";
+    this.#import.slot = inline ? "" : "actions";
+
+    if (inline) {
+      this.#actions.append(this.#reset, this.#import);
+      root.append(this.#controls, this.#actions);
+      this.#button.remove();
+      this.#popover.remove();
+    } else {
+      this.#popover.append(this.#controls, this.#reset, this.#import);
+      root.prepend(this.#button, this.#popover);
+      this.#actions.remove();
+    }
+  }
+
   #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();
     });
@@ -199,10 +285,10 @@ export class GwThemePicker extends GwElement {
       this.theme = this.#gallery.theme;
       this.dispatchEvent(this.#detail("theme", { id: this.theme }));
     });
-    this.#popover.querySelector(".import")?.addEventListener("click", () => {
+    this.#import.addEventListener("click", () => {
       this.#file.click();
     });
-    this.#popover.querySelector(".reset")?.addEventListener("click", () => {
+    this.#reset.addEventListener("click", () => {
       this.dispatchEvent(new Event("reset", { bubbles: true, composed: true }));
     });
     this.#file.addEventListener("change", async () => {
@@ -217,14 +303,33 @@ export class GwThemePicker extends GwElement {
       this.dispatchEvent(this.#detail("import", { text, name: file.name }));
     });
 
-    root.append(this.#button, this.#popover, this.#file);
+    root.append(this.#file);
+    this.#place(root);
   }
 
-  protected override update() {
-    this.#button.label = this.label;
-    this.#button.textContent = this.label;
+  protected override update(changed: ReadonlySet<string>) {
+    const root = this.shadowRoot;
+
+    if (changed.has("layout") && root !== null) this.#place(root);
+
+    const offered = this.#offered();
+    const current = offered.find(({ value }) => value === this.mode);
+
+    if (this.layout === "cycle") {
+      const name = `${this.label}: ${current?.label ?? this.mode}`;
+
+      this.#button.label = name;
+      this.#button.textContent = name;
+      this.#button.icon = current?.icon ?? paletteIcon;
+    } else {
+      this.#button.label = this.label;
+      this.#button.textContent = this.label;
+      this.#button.icon = paletteIcon;
+    }
+
     this.#popover.heading = this.label;
     this.#mode.label = "Mode";
+    this.#mode.options = offered.map(({ value, label }) => ({ value, label }));
     this.#mode.value = this.mode;
     this.#theme.options = Array.isArray(this.themes) ? this.themes : [];
     this.#theme.value = this.theme;

package/src/gw-toast.ts

@@ -22,6 +22,8 @@ import { base, type Tone } from "./styles.js";
  * @summary Brief, non-interactive toasts in the bottom end corner.
  *
  * @attr {number} duration - Milliseconds each toast shows for. Defaults to 5000.
+ *
+ * @csspart toast - Each toast.
  */
 export class GwToaster extends GwElement {
   static override properties = {
@@ -111,7 +113,7 @@ export class GwToaster extends GwElement {
   }
 
   show(message: string, tone: Tone = "neutral") {
-    const toast = h("div", { class: "toast" }, message);
+    const toast = h("div", { class: "toast", part: "toast" }, message);
 
     toast.style.setProperty(
       "--gw-toast-tone",