@timmo001/groundwork-ui 0.0.0-stage → 0.0.0

package/src/gw-menu-button.ts

@@ -0,0 +1,386 @@
+/**
+ * `gw-menu-button`: a button that opens a menu of items and actions.
+ * Docs: https://groundwork.timmo.dev/components/actions/#menu-button
+ *
+ * @module
+ */
+import { GwElement, css, h } from "./element.js";
+import { base, createIcon, setIconPath } from "./styles.js";
+
+export interface MenuItem {
+  readonly value: string;
+  readonly label: string;
+  /** A second line, such as what the item does. */
+  readonly description?: string;
+  /** SVG path data for an icon before the label. */
+  readonly icon?: string;
+  readonly disabled?: boolean;
+}
+
+/**
+ * A button that opens a menu on the Popover API, so it shows in the top
+ * layer and closes on Esc or a click outside. Set `items`; arrow keys, Home
+ * and End move between them, and choosing one fires `select` with its
+ * `value` and closes the menu.
+ *
+ * Contextual actions, such as "Add a schedule", go in `actions`: they stay
+ * below the items as the list scrolls, so they're found without scrolling to
+ * the end, and with no items the menu says `empty` above them.
+ *
+ * Items render inside the component, so a page's own button styles can't
+ * reach them.
+ *
+ * @element gw-menu-button
+ * @summary A button that opens a menu of items and actions.
+ *
+ * @attr {string} label - The trigger's text.
+ * @attr {string} icon - SVG path data for an icon before the trigger's text.
+ * @attr {string} empty - What the menu says with no items. Defaults to `Nothing here yet`.
+ * @attr {MenuItem[]} items - The items, as JSON.
+ * @attr {MenuItem[]} actions - Actions pinned under the items, as JSON.
+ *
+ * @csspart trigger - The button that opens the menu.
+ *
+ * @fires select - When an item or action is chosen, with its `value` in `detail`.
+ */
+export class GwMenuButton extends GwElement {
+  static override properties = {
+    label: {},
+    icon: {},
+    empty: {},
+    items: { type: "json" },
+    actions: { type: "json" },
+  } as const;
+
+  static override styles = [
+    base,
+    css`
+      :host {
+        position: relative;
+        display: inline-block;
+        anchor-scope: --gw-menu;
+      }
+
+      .trigger {
+        display: inline-flex;
+        gap: var(--gw-space-2);
+        align-items: center;
+        box-sizing: border-box;
+        height: 2.5rem;
+        padding: 0 var(--gw-space-4);
+        font: inherit;
+        font-size: var(--gw-font-size-s);
+        font-weight: var(--gw-font-weight-strong);
+        color: var(--gw-color-text-strong);
+        cursor: pointer;
+        background: var(--gw-color-fill-neutral-resting);
+        border: var(--gw-border-width) solid var(--gw-border-color);
+        border-radius: var(--gw-radius-control);
+        transition: background-color var(--gw-motion-fast)
+          var(--gw-motion-easing);
+        anchor-name: --gw-menu;
+      }
+
+      .trigger:hover {
+        background: var(--gw-color-fill-neutral-hovered);
+      }
+
+      .chevron {
+        width: 0.4rem;
+        height: 0.4rem;
+        margin-inline-start: var(--gw-space-1);
+        border-inline-end: 1.5px solid currentColor;
+        border-block-end: 1.5px solid currentColor;
+        rotate: 45deg;
+        translate: 0 -0.125rem;
+        transition:
+          rotate var(--gw-motion-normal) var(--gw-motion-easing),
+          translate var(--gw-motion-normal) var(--gw-motion-easing);
+      }
+
+      .trigger[aria-expanded="true"] .chevron {
+        rotate: 225deg;
+        translate: 0 0.125rem;
+      }
+
+      [popover] {
+        position-anchor: --gw-menu;
+        position-try-fallbacks: flip-block, flip-inline;
+        inset: auto;
+        top: anchor(bottom);
+        left: anchor(left);
+        box-sizing: border-box;
+        min-width: 15rem;
+        max-height: min(24rem, 60vh);
+        padding: 0;
+        margin: var(--gw-space-1) 0 0;
+        overflow: hidden;
+        color: var(--gw-color-text-primary);
+        background: var(--gw-color-surface-overlay);
+        border: max(var(--gw-border-width), 1px) solid
+          var(--gw-color-border-normal);
+        border-radius: var(--gw-radius-l);
+        box-shadow: var(--gw-shadow-m);
+        opacity: 0;
+        translate: 0 -0.25rem;
+        transition:
+          opacity var(--gw-motion-fast) var(--gw-motion-easing),
+          translate var(--gw-motion-normal) var(--gw-motion-easing),
+          display var(--gw-motion-normal) allow-discrete,
+          overlay var(--gw-motion-normal) allow-discrete;
+      }
+
+      [popover]:popover-open {
+        display: flex;
+        flex-direction: column;
+        opacity: 1;
+        translate: 0 0;
+      }
+
+      @starting-style {
+        [popover]:popover-open {
+          opacity: 0;
+          translate: 0 -0.25rem;
+        }
+      }
+
+      /* The items scroll; the actions stay put below them, so "Add" is always
+         in reach rather than at the end of a long list */
+      .items,
+      .actions {
+        display: flex;
+        flex-direction: column;
+        gap: var(--gw-space-0-5);
+        padding: var(--gw-space-1);
+      }
+
+      .items {
+        flex: 1;
+        min-height: 0;
+        overflow-y: auto;
+      }
+
+      .actions {
+        border-block-start: max(var(--gw-border-width), 1px) solid
+          var(--gw-color-border-normal);
+      }
+
+      .empty {
+        padding: var(--gw-space-3);
+        margin: 0;
+        font-size: var(--gw-font-size-s);
+        color: var(--gw-color-text-secondary);
+      }
+
+      .item {
+        display: flex;
+        gap: var(--gw-space-3);
+        align-items: center;
+        box-sizing: border-box;
+        min-height: 2.5rem;
+        padding: var(--gw-space-2) var(--gw-space-3);
+        font: inherit;
+        font-size: var(--gw-font-size-s);
+        color: var(--gw-color-text-primary);
+        text-align: start;
+        cursor: pointer;
+        background: transparent;
+        border: 0;
+        border-radius: var(--gw-radius-m);
+        transition: background-color var(--gw-motion-fast)
+          var(--gw-motion-easing);
+        --gw-icon-size: 1.125rem;
+      }
+
+      .item:hover,
+      .item:focus-visible {
+        background: var(--gw-color-fill-neutral-hovered);
+        outline: none;
+      }
+
+      .item:focus-visible {
+        box-shadow: inset 0 0 0 var(--gw-focus-width) var(--gw-color-focus);
+      }
+
+      .item:disabled {
+        color: var(--gw-color-text-disabled);
+        cursor: not-allowed;
+        background: transparent;
+      }
+
+      .action {
+        font-weight: var(--gw-font-weight-strong);
+        color: var(--gw-color-accent);
+      }
+
+      .text {
+        display: flex;
+        flex-direction: column;
+        gap: var(--gw-space-0-5);
+      }
+
+      .description {
+        font-size: var(--gw-font-size-xs);
+        color: var(--gw-color-text-secondary);
+      }
+    `,
+  ];
+
+  declare label: string;
+  /** SVG path data for an icon before the trigger's label. */
+  declare icon: string;
+  /** What the menu says when it has no items, such as "No backups yet". */
+  declare empty: string;
+  declare items: readonly MenuItem[];
+  declare actions: readonly MenuItem[];
+
+  readonly #trigger = h("button", {
+    class: "trigger",
+    part: "trigger",
+    popovertarget: "menu",
+    "aria-haspopup": "menu",
+    "aria-expanded": "false",
+  });
+
+  readonly #triggerText = document.createTextNode("");
+
+  readonly #triggerIcon = createIcon("");
+
+  readonly #items = h("div", { class: "items", role: "none" });
+
+  readonly #actions = h("div", { class: "actions", role: "none" });
+
+  readonly #popover = h(
+    "div",
+    { id: "menu", popover: "auto", role: "menu" },
+    this.#items,
+    this.#actions,
+  );
+
+  constructor() {
+    super();
+    this.label = "";
+    this.icon = "";
+    this.empty = "Nothing here yet";
+    this.items = [];
+    this.actions = [];
+  }
+
+  /** The enabled items then actions, in the order arrow keys move through them. */
+  get #buttons() {
+    return [...this.#popover.querySelectorAll("button")].filter(
+      (button) => !button.disabled,
+    );
+  }
+
+  readonly #onToggle = (event: ToggleEvent) => {
+    const expanded = event.newState === "open";
+
+    this.#trigger.setAttribute("aria-expanded", String(expanded));
+
+    if (expanded) this.#buttons[0]?.focus();
+  };
+
+  readonly #onKeydown = (event: KeyboardEvent) => {
+    const buttons = this.#buttons;
+
+    const index = buttons.findIndex(
+      (button) => button === this.shadowRoot?.activeElement,
+    );
+
+    const next = {
+      ArrowDown: (index + 1) % buttons.length,
+      ArrowUp: (index - 1 + buttons.length) % buttons.length,
+      Home: 0,
+      End: buttons.length - 1,
+    }[event.key];
+
+    if (next === undefined) return;
+
+    event.preventDefault();
+    buttons[next]?.focus();
+  };
+
+  #choose(value: string) {
+    this.dispatchEvent(
+      new CustomEvent("select", {
+        detail: { value },
+        bubbles: true,
+        composed: true,
+      }),
+    );
+
+    this.#popover.hidePopover();
+    this.#trigger.focus();
+  }
+
+  #renderItem(item: MenuItem, kind: "item" | "action") {
+    const button = h(
+      "button",
+      {
+        class: kind === "action" ? "item action" : "item",
+        role: "menuitem",
+        value: item.value,
+        disabled: item.disabled === true,
+      },
+      item.icon ? createIcon(item.icon) : null,
+      h(
+        "span",
+        { class: "text" },
+        h("span", {}, item.label),
+        item.description
+          ? h("span", { class: "description" }, item.description)
+          : null,
+      ),
+    );
+
+    button.addEventListener("click", () => this.#choose(item.value));
+
+    return button;
+  }
+
+  protected override create(root: ShadowRoot) {
+    this.#trigger.append(
+      this.#triggerIcon,
+      this.#triggerText,
+      h("span", { class: "chevron", "aria-hidden": "true" }),
+    );
+    this.#popover.addEventListener("toggle", this.#onToggle);
+    this.#popover.addEventListener("keydown", this.#onKeydown);
+    root.append(this.#trigger, this.#popover);
+  }
+
+  protected override update(changed: ReadonlySet<string>) {
+    this.#triggerText.data = this.label;
+    setIconPath(this.#triggerIcon, this.icon);
+    this.#triggerIcon.toggleAttribute("hidden", !this.icon);
+    this.#popover.setAttribute("aria-label", this.label);
+
+    if (changed.has("items") || changed.has("empty")) {
+      const items = Array.isArray(this.items) ? this.items : [];
+
+      this.#items.replaceChildren(
+        ...(items.length === 0
+          ? [h("p", { class: "empty", role: "none" }, this.empty)]
+          : items.map((item) => this.#renderItem(item, "item"))),
+      );
+    }
+
+    if (changed.has("actions")) {
+      const actions = Array.isArray(this.actions) ? this.actions : [];
+
+      this.#actions.replaceChildren(
+        ...actions.map((item) => this.#renderItem(item, "action")),
+      );
+      this.#actions.hidden = actions.length === 0;
+    }
+  }
+}
+
+GwMenuButton.define("gw-menu-button");
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "gw-menu-button": GwMenuButton;
+  }
+}

package/src/gw-meter.ts

@@ -0,0 +1,194 @@
+/**
+ * `gw-meter`: a labeled bar for a value in a range.
+ * Docs: https://groundwork.timmo.dev/components/display/#meter
+ *
+ * @module
+ */
+import { GwElement, css, h, setAttribute } from "./element.js";
+import "./gw-skeleton.js";
+import { fadeIn } from "./motion.js";
+import { base, type Tone } from "./styles.js";
+
+/**
+ * A labeled bar for a value in a range, such as disk use. Past `high` it
+ * turns warning, and past `critical` danger, unless a `tone` is set. While
+ * `loading`, the track pulses and a skeleton stands in for the value.
+ *
+ * @element gw-meter
+ * @summary A labeled bar for a value in a range.
+ *
+ * @attr {string} label - What it measures.
+ * @attr {number} value - The value. Defaults to 0.
+ * @attr {number} min - The bottom of the range. Defaults to 0.
+ * @attr {number} max - The top of the range. Defaults to 100.
+ * @attr {number} high - Past this it turns warning.
+ * @attr {number} critical - Past this it turns danger.
+ * @attr {string} display - The value as shown, such as `42 GB`. Defaults to a percentage.
+ * @attr {"neutral"|"accent"|"info"|"success"|"warning"|"danger"|"important"} tone - A fixed color, overriding `high` and `critical`.
+ * @attr {boolean} loading - Pulses the track and shows a skeleton for the value.
+ */
+export class GwMeter extends GwElement {
+  static override properties = {
+    label: {},
+    value: { type: "number" },
+    min: { type: "number" },
+    max: { type: "number" },
+    high: { type: "number" },
+    critical: { type: "number" },
+    display: {},
+    tone: { reflect: true },
+    loading: { type: "boolean", reflect: true },
+  } as const;
+
+  static override styles = [
+    base,
+    css`
+      :host {
+        display: block;
+      }
+
+      .top {
+        display: flex;
+        gap: var(--gw-space-2);
+        justify-content: space-between;
+        margin-block-end: var(--gw-space-1);
+        font-size: var(--gw-font-size-s);
+      }
+
+      .value {
+        font-variant-numeric: var(--gw-font-figures);
+        color: var(--gw-color-text-strong);
+      }
+
+      .track {
+        height: 0.5rem;
+        overflow: hidden;
+        background: var(--gw-color-surface-lower);
+        border: var(--gw-border-width) solid var(--gw-color-border-quiet);
+        border-radius: var(--gw-radius-pill);
+      }
+
+      .fill {
+        height: 100%;
+        background: var(--gw-meter-color, var(--gw-color-fill-accent-resting));
+        border-radius: inherit;
+        transition: width var(--gw-motion-slow) var(--gw-motion-easing);
+      }
+
+      .bar {
+        min-height: 0;
+        height: 0.5rem;
+        --gw-skeleton-radius: var(--gw-radius-pill);
+      }
+    `,
+  ];
+
+  declare label: string;
+  declare value: number;
+  declare min: number;
+  declare max: number;
+  declare high: number | undefined;
+  declare critical: number | undefined;
+  declare display: string;
+  declare tone: Tone | undefined;
+  declare loading: boolean;
+
+  readonly #top = h("div", { class: "top" });
+
+  readonly #label = h("span");
+
+  readonly #labelSkeleton = h("gw-skeleton-text", {
+    style: "--gw-skeleton-width: 6rem",
+  });
+
+  readonly #value = h("span", { class: "value", "aria-hidden": "true" });
+
+  readonly #valueSkeleton = h("gw-skeleton-text", {
+    style: "--gw-skeleton-width: 2.5rem",
+  });
+
+  readonly #fill = h("div", { class: "fill" });
+
+  readonly #track = h("div", { class: "track", role: "meter" }, this.#fill);
+
+  readonly #bar = h("gw-skeleton", { class: "bar" });
+
+  #rendered = false;
+
+  constructor() {
+    super();
+    this.label = "";
+    this.value = 0;
+    this.min = 0;
+    this.max = 100;
+    this.high = undefined;
+    this.critical = undefined;
+    this.display = "";
+    this.tone = undefined;
+    this.loading = false;
+  }
+
+  get #color() {
+    if (this.tone !== undefined) return "var(--gw-tone)";
+
+    if (this.critical !== undefined && this.value >= this.critical) {
+      return "var(--gw-color-danger)";
+    }
+
+    if (this.high !== undefined && this.value >= this.high) {
+      return "var(--gw-color-warning)";
+    }
+
+    return "var(--gw-color-fill-accent-resting)";
+  }
+
+  protected override create(root: ShadowRoot) {
+    this.#top.append(
+      h("span", {}, this.#label, this.#labelSkeleton),
+      this.#value,
+      this.#valueSkeleton,
+    );
+    root.append(this.#top, this.#track, this.#bar);
+  }
+
+  protected override update(changed: ReadonlySet<string>) {
+    const span = this.max - this.min || 1;
+
+    const percent = Math.min(
+      100,
+      Math.max(0, ((this.value - this.min) / span) * 100),
+    );
+
+    const text = this.display || `${Math.round(percent)}%`;
+
+    setAttribute(this.#top, "aria-busy", this.loading ? "true" : null);
+    this.#label.textContent = this.label;
+    this.#labelSkeleton.hidden = !this.loading || this.label !== "";
+    this.#value.textContent = text;
+    this.#value.hidden = this.loading;
+    this.#valueSkeleton.hidden = !this.loading;
+    this.#track.hidden = this.loading;
+    this.#bar.hidden = !this.loading;
+    setAttribute(this.#track, "aria-label", this.label || null);
+    setAttribute(this.#track, "aria-valuemin", this.min);
+    setAttribute(this.#track, "aria-valuemax", this.max);
+    setAttribute(this.#track, "aria-valuenow", this.value);
+    setAttribute(this.#track, "aria-valuetext", text);
+    this.#fill.style.width = `${percent}%`;
+    this.#fill.style.setProperty("--gw-meter-color", this.#color);
+
+    if (this.#rendered && changed.has("loading") && !this.loading) {
+      fadeIn(this.#value);
+    }
+
+    this.#rendered = true;
+  }
+}
+
+GwMeter.define("gw-meter");
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "gw-meter": GwMeter;
+  }
+}