@timmo001/groundwork-ui 0.0.0-stage → 0.0.0

package/src/gw-facts.ts

@@ -0,0 +1,141 @@
+/**
+ * `gw-facts`: label and value pairs, as a description list.
+ * Docs: https://groundwork.timmo.dev/components/display/#facts
+ *
+ * @module
+ */
+import { GwElement, css, h } from "./element.js";
+import "./gw-skeleton.js";
+import { animateHeight, fadeIn } from "./motion.js";
+import { base } from "./styles.js";
+
+export interface Fact {
+  readonly label: string;
+  readonly value: string;
+}
+
+/** Widths for skeleton values, so the rows don't read as a solid block. */
+const skeletonWidths = ["60%", "40%", "75%", "50%", "65%"];
+
+/**
+ * Label and value pairs, as a description list. While `loading`, `rows`
+ * skeleton pairs stand in for them, keeping any labels already known. The
+ * list glides to its new height and the values fade in once they've loaded.
+ *
+ * @element gw-facts
+ * @summary Label and value pairs, as a description list.
+ *
+ * @attr {Fact[]} items - The pairs, as JSON.
+ * @attr {boolean} loading - Shows skeleton pairs, keeping any labels already known.
+ * @attr {number} rows - How many skeleton pairs while loading. Defaults to 4.
+ */
+export class GwFacts extends GwElement {
+  static override properties = {
+    items: { type: "json" },
+    loading: { type: "boolean", reflect: true },
+    rows: { type: "number" },
+  } as const;
+
+  static override styles = [
+    base,
+    css`
+      :host {
+        display: block;
+      }
+
+      dl {
+        display: grid;
+        grid-template-columns: minmax(7rem, max-content) 1fr;
+        gap: var(--gw-space-1) var(--gw-space-3);
+        margin: 0;
+        font-size: var(--gw-font-size-s);
+      }
+
+      dt {
+        color: var(--gw-color-text-secondary);
+      }
+
+      dd {
+        min-width: 0;
+        margin: 0;
+        font-variant-numeric: var(--gw-font-figures);
+        color: var(--gw-color-text-strong);
+        overflow-wrap: anywhere;
+      }
+    `,
+  ];
+
+  declare items: readonly Fact[];
+  declare loading: boolean;
+  declare rows: number;
+
+  readonly #list = h("dl");
+
+  #rendered = false;
+
+  constructor() {
+    super();
+    this.items = [];
+    this.loading = false;
+    this.rows = 4;
+  }
+
+  protected override create(root: ShadowRoot) {
+    root.append(this.#list);
+  }
+
+  protected override update(changed: ReadonlySet<string>) {
+    const items = Array.isArray(this.items) ? this.items : [];
+    const before = this.#rendered ? this.offsetHeight : 0;
+    const loaded = this.#rendered && changed.has("loading") && !this.loading;
+
+    if (this.loading) {
+      const count = Math.max(this.rows, items.length);
+
+      this.#list.setAttribute("aria-busy", "true");
+      this.#list.replaceChildren(
+        ...Array.from({ length: count }, (_, index) => [
+          h(
+            "dt",
+            {},
+            items[index]?.label ??
+              h("gw-skeleton-text", { style: "--gw-skeleton-width: 5rem" }),
+          ),
+          h(
+            "dd",
+            {},
+            h("gw-skeleton-text", {
+              style: `--gw-skeleton-width: ${skeletonWidths[index % skeletonWidths.length]}`,
+            }),
+          ),
+        ]).flat(),
+      );
+    } else {
+      this.#list.removeAttribute("aria-busy");
+      this.#list.replaceChildren(
+        ...items.flatMap((item) => [
+          h("dt", {}, item.label),
+          h("dd", {}, loaded ? h("span", {}, item.value) : item.value),
+        ]),
+      );
+    }
+
+    if (before > 0) animateHeight(this, before);
+
+    if (loaded) {
+      for (const value of this.#list.querySelectorAll("dd > span")) {
+        if (value instanceof HTMLElement) fadeIn(value);
+      }
+    }
+
+    this.#rendered = true;
+  }
+}
+
+GwFacts.define("gw-facts");
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "gw-facts": GwFacts;
+  }
+}

package/src/gw-fade-in.ts

@@ -0,0 +1,108 @@
+/**
+ * `gw-fade-in`: fades its content in after a delay.
+ * Docs: https://groundwork.timmo.dev/components/feedback/#fading-in
+ *
+ * @module
+ */
+import { GwElement, css, h } from "./element.js";
+import { fadeEasing, fadeIn, motionDuration, reducedMotion } from "./motion.js";
+
+/**
+ * Waits `delay` milliseconds, then fades its content in over `duration`.
+ * Wrap a skeleton in one with a delay, so a quick load never flashes a
+ * placeholder, and wrap content as it arrives so it eases in rather than
+ * popping. With reduced motion it still waits, then shows at once. The tokens
+ * stylesheet hides it until it's defined, so its content never shows first.
+ *
+ * @element gw-fade-in
+ * @summary Fades its content in after a delay.
+ *
+ * @attr {number} delay - Milliseconds to wait before fading in. Defaults to 0.
+ * @attr {number} duration - Milliseconds the fade takes. Defaults to `--gw-motion-slow`.
+ *
+ * @slot - The content to fade in.
+ */
+export class GwFadeIn extends GwElement {
+  static override properties = {
+    delay: { type: "number" },
+    duration: { type: "number" },
+  } as const;
+
+  static override styles = [
+    css`
+      :host {
+        display: block;
+      }
+    `,
+  ];
+
+  declare delay: number;
+  declare duration: number | undefined;
+
+  #animation: Animation | undefined;
+
+  constructor() {
+    super();
+    this.delay = 0;
+    this.duration = undefined;
+  }
+
+  protected override create(root: ShadowRoot) {
+    root.append(h("slot"));
+  }
+
+  override connectedCallback() {
+    super.connectedCallback();
+    this.#fadeIn();
+  }
+
+  override disconnectedCallback() {
+    this.#animation?.cancel();
+    this.#animation = undefined;
+  }
+
+  /** Fades the content out, then runs the wait and fade in again. */
+  async replay() {
+    const from = Number(getComputedStyle(this).opacity);
+
+    if (from > 0 && !reducedMotion()) {
+      this.#animation?.cancel();
+
+      const out = this.animate([{ opacity: from }, { opacity: 0 }], {
+        duration: motionDuration(this, "--gw-motion-fast", 150),
+        easing: fadeEasing,
+        fill: "forwards",
+      });
+
+      this.#animation = out;
+
+      try {
+        await out.finished;
+      } catch {
+        return;
+      }
+
+      if (this.#animation !== out) return;
+    }
+
+    this.#fadeIn();
+  }
+
+  #fadeIn() {
+    this.#animation?.cancel();
+    this.#animation = fadeIn(
+      this,
+      this.duration && this.duration > 0
+        ? { delay: this.delay || 0, duration: this.duration }
+        : { delay: this.delay || 0 },
+    );
+  }
+}
+
+GwFadeIn.define("gw-fade-in");
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "gw-fade-in": GwFadeIn;
+  }
+}

package/src/gw-gauge.ts

@@ -0,0 +1,328 @@
+/**
+ * `gw-gauge`: a reading on a dial.
+ * Docs: https://groundwork.timmo.dev/components/display/#gauge
+ *
+ * @module
+ */
+import { GwElement, css, h, setAttribute } from "./element.js";
+import "./gw-skeleton.js";
+import { fadeIn } from "./motion.js";
+import { base } from "./styles.js";
+
+/** How much of the circle the gauge's track covers. */
+const sweep = 270;
+
+const radius = 40;
+
+const circumference = 2 * Math.PI * radius;
+
+const track = (circumference * sweep) / 360;
+
+/**
+ * The color a reading shows in: the accent until it reaches `warning`, then
+ * the warning and danger colors. Lower is worse when `inverted`, such as for
+ * a battery.
+ */
+export const severityColor = (
+  value: number | undefined,
+  warning: number,
+  danger: number,
+  inverted = false,
+) => {
+  if (value === undefined) return "var(--gw-color-text-disabled)";
+
+  const worse = (limit: number) => (inverted ? value <= limit : value >= limit);
+
+  if (worse(danger)) return "var(--gw-color-danger)";
+
+  if (worse(warning)) return "var(--gw-color-warning)";
+
+  return "var(--gw-gauge-color, var(--gw-color-fill-accent-resting))";
+};
+
+const circle = (className: string) => {
+  const element = document.createElementNS(
+    "http://www.w3.org/2000/svg",
+    "circle",
+  );
+
+  element.setAttribute("class", className);
+  element.setAttribute("cx", "50");
+  element.setAttribute("cy", "50");
+  element.setAttribute("r", String(radius));
+  element.setAttribute("stroke-dasharray", `${track} ${circumference}`);
+
+  return element;
+};
+
+/**
+ * A reading on a dial. The arc fills to `value` between `min` and `max`,
+ * colored by `warning` and `danger`, and glides when the value changes.
+ * While `loading`, the track pulses and a skeleton stands in for the
+ * reading.
+ *
+ * @element gw-gauge
+ * @summary A reading on a dial.
+ *
+ * @attr {number} value - The reading.
+ * @attr {number} min - The bottom of the dial. Defaults to 0.
+ * @attr {number} max - The top of the dial. Defaults to 100.
+ * @attr {string} display - The reading as shown, in place of `value`.
+ * @attr {string} unit - The unit after the reading. Defaults to `%`.
+ * @attr {string} label - What it measures, under the dial.
+ * @attr {string} caption - A line under the label.
+ * @attr {number} warning - From here it turns warning. Defaults to 75.
+ * @attr {number} danger - From here it turns danger. Defaults to 90.
+ * @attr {boolean} inverted - Lower is worse, such as for a battery.
+ * @attr {boolean} loading - Pulses the track and shows a skeleton for the reading.
+ *
+ * @cssprop --gw-gauge-size - The dial's width. Defaults to `8.5rem`.
+ * @cssprop --gw-gauge-color - The arc's color, overriding the thresholds.
+ */
+export class GwGauge extends GwElement {
+  static override properties = {
+    value: { type: "number" },
+    min: { type: "number" },
+    max: { type: "number" },
+    display: {},
+    unit: {},
+    label: {},
+    caption: {},
+    warning: { type: "number" },
+    danger: { type: "number" },
+    inverted: { type: "boolean" },
+    loading: { type: "boolean", reflect: true },
+  } as const;
+
+  static override styles = [
+    base,
+    css`
+      :host {
+        display: inline-flex;
+        flex-direction: column;
+        gap: var(--gw-space-1);
+        /* Dials line up in a row even when only some have captions */
+        align-self: flex-start;
+        align-items: center;
+        width: var(--gw-gauge-size, 8.5rem);
+      }
+
+      .dial {
+        position: relative;
+        width: 100%;
+        aspect-ratio: 1;
+      }
+
+      svg {
+        width: 100%;
+        height: 100%;
+        /* Start the arc at the bottom left, leaving the gap at the bottom */
+        rotate: ${90 + (360 - sweep) / 2}deg;
+      }
+
+      circle {
+        fill: none;
+        stroke-width: 9;
+        stroke-linecap: round;
+      }
+
+      .track {
+        stroke: var(--gw-color-surface-lower);
+      }
+
+      :host([loading]) .track {
+        stroke: var(--gw-color-fill-neutral-resting);
+        animation: pulse 2s ease-in-out infinite;
+      }
+
+      @keyframes pulse {
+        50% {
+          opacity: 0.45;
+        }
+      }
+
+      .reading gw-skeleton-text {
+        font-size: calc(var(--gw-gauge-size, 8.5rem) * 0.2);
+      }
+
+      .fill {
+        transition:
+          stroke-dashoffset var(--gw-motion-slow) var(--gw-motion-easing),
+          stroke var(--gw-motion-normal) var(--gw-motion-easing);
+      }
+
+      .reading {
+        position: absolute;
+        inset: 0;
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        padding-block-start: 6%;
+      }
+
+      .shown:not([hidden]) {
+        display: contents;
+      }
+
+      .value {
+        font-size: calc(var(--gw-gauge-size, 8.5rem) * 0.2);
+        font-weight: var(--gw-font-weight-strong);
+        font-variant-numeric: var(--gw-font-figures);
+        line-height: 1;
+        color: var(--gw-color-text-strong);
+      }
+
+      .unit,
+      .caption {
+        font-size: var(--gw-font-size-xs);
+        color: var(--gw-color-text-secondary);
+      }
+
+      .label {
+        margin-block-start: calc(var(--gw-gauge-size, 8.5rem) * -0.12);
+        font-size: var(--gw-font-size-s);
+        font-weight: var(--gw-font-weight-strong);
+        text-align: center;
+      }
+
+      .caption {
+        text-align: center;
+      }
+    `,
+  ];
+
+  declare value: number | undefined;
+  declare min: number;
+  declare max: number;
+  /** The text in the middle. Defaults to the rounded value. */
+  declare display: string;
+  declare unit: string;
+  declare label: string;
+  declare caption: string;
+  declare warning: number;
+  declare danger: number;
+  /** Lower readings are worse, such as for a battery. */
+  declare inverted: boolean;
+  declare loading: boolean;
+
+  readonly #fill = circle("fill");
+
+  readonly #dial = h("div", { class: "dial", role: "meter" });
+
+  readonly #value = h("span", { class: "value" });
+
+  readonly #unit = h("span", { class: "unit" });
+
+  readonly #shown = h("span", { class: "shown" }, this.#value, this.#unit);
+
+  readonly #readingSkeleton = h("gw-skeleton-text", {
+    style: "--gw-skeleton-width: 2em",
+  });
+
+  readonly #label = h("span", { class: "label" });
+
+  readonly #caption = h("span", { class: "caption" });
+
+  readonly #captionSkeleton = h("gw-skeleton-text", {
+    style: "--gw-skeleton-width: 5rem",
+  });
+
+  #rendered = false;
+
+  constructor() {
+    super();
+    this.value = undefined;
+    this.min = 0;
+    this.max = 100;
+    this.display = "";
+    this.unit = "%";
+    this.label = "";
+    this.caption = "";
+    this.warning = 75;
+    this.danger = 90;
+    this.inverted = false;
+    this.loading = false;
+  }
+
+  protected override create(root: ShadowRoot) {
+    const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+
+    svg.setAttribute("viewBox", "0 0 100 100");
+    svg.setAttribute("aria-hidden", "true");
+    svg.append(circle("track"), this.#fill);
+    this.#dial.append(
+      svg,
+      h("div", { class: "reading" }, this.#readingSkeleton, this.#shown),
+    );
+    root.append(this.#dial, this.#label, this.#captionSkeleton, this.#caption);
+  }
+
+  protected override update(changed: ReadonlySet<string>) {
+    const value =
+      this.value !== undefined && Number.isFinite(this.value) && !this.loading
+        ? this.value
+        : undefined;
+
+    const span = this.max - this.min || 1;
+
+    const fraction =
+      value === undefined
+        ? 0
+        : Math.min(1, Math.max(0, (value - this.min) / span));
+
+    const shown =
+      this.display || (value === undefined ? "-" : String(Math.round(value)));
+
+    const text = this.loading
+      ? "Loading"
+      : value === undefined
+        ? "Unknown"
+        : [`${shown}${this.unit}`, this.caption]
+            .filter((part) => part !== "")
+            .join(", ");
+
+    setAttribute(this.#dial, "aria-busy", this.loading ? "true" : null);
+    setAttribute(this.#dial, "aria-label", this.label || null);
+    setAttribute(this.#dial, "aria-valuemin", this.min);
+    setAttribute(this.#dial, "aria-valuemax", this.max);
+    // A meter needs a value; while loading or unknown, the text says so
+    setAttribute(this.#dial, "aria-valuenow", value ?? this.min);
+    setAttribute(this.#dial, "aria-valuetext", text);
+    this.#fill.setAttribute(
+      "stroke",
+      severityColor(value, this.warning, this.danger, this.inverted),
+    );
+    this.#fill.setAttribute(
+      "stroke-dashoffset",
+      String(track * (1 - fraction)),
+    );
+    this.#fill.setAttribute("opacity", fraction === 0 ? "0" : "1");
+    this.#readingSkeleton.hidden = !this.loading;
+    this.#shown.hidden = this.loading;
+    this.#value.textContent = shown;
+    this.#unit.textContent = this.unit;
+    this.#unit.hidden = this.unit === "";
+    this.#label.textContent = this.label;
+    this.#label.hidden = this.label === "";
+    this.#captionSkeleton.hidden = !this.loading || this.caption === "";
+    this.#caption.textContent = this.caption;
+    this.#caption.hidden = this.loading || this.caption === "";
+
+    if (this.#rendered && changed.has("loading") && !this.loading) {
+      fadeIn(this.#value);
+      fadeIn(this.#unit);
+      fadeIn(this.#caption);
+    }
+
+    this.#rendered = true;
+  }
+}
+
+GwGauge.define("gw-gauge");
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "gw-gauge": GwGauge;
+  }
+}

package/src/gw-input.ts

@@ -0,0 +1,127 @@
+/**
+ * `gw-input`: a labeled native input in light DOM.
+ * Docs: https://groundwork.timmo.dev/components/inputs/#input
+ *
+ * @module
+ */
+import { h, setAttribute } from "./element.js";
+import { FieldInfo } from "./field-info.js";
+import { LightElement, fieldId } from "./fields.js";
+
+/**
+ * A labeled native `<input>`, with an optional hint and error.
+ *
+ * @element gw-input
+ * @summary A labeled text field in light DOM, so forms and autofill see it.
+ *
+ * @attr {string} label - The field's label.
+ * @attr {string} name - The form field name.
+ * @attr {string} type - The native input type. Defaults to `text`.
+ * @attr {string} value - The value.
+ * @attr {string} placeholder - Placeholder text.
+ * @attr {string} autocomplete - The native autocomplete hint.
+ * @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} error - An error under the field, which marks it invalid.
+ * @attr {boolean} required - Requires a value.
+ * @attr {boolean} disabled - Disables the field.
+ */
+export class GwInput extends LightElement {
+  static override properties = {
+    label: {},
+    name: {},
+    type: {},
+    value: {},
+    placeholder: {},
+    autocomplete: {},
+    hint: {},
+    info: {},
+    error: {},
+    required: { type: "boolean" },
+    disabled: { type: "boolean" },
+  } as const;
+
+  declare label: string;
+  declare name: string;
+  declare type: string;
+  declare value: string;
+  declare placeholder: string;
+  declare autocomplete: string;
+  declare hint: string;
+  /** Longer help, opened from an (i) button by the label. */
+  declare info: string;
+  declare error: string;
+  declare required: boolean;
+  declare disabled: boolean;
+
+  readonly #id = fieldId();
+
+  readonly #label = h("label", { for: this.#id });
+
+  readonly #info = new FieldInfo(this.#label);
+
+  readonly #input = h("input", { id: this.#id });
+
+  readonly #hint = h("p", { class: "gw-hint", id: `${this.#id}-hint` });
+
+  readonly #error = h("p", { class: "gw-error", id: `${this.#id}-error` });
+
+  constructor() {
+    super();
+    this.label = "";
+    this.name = "";
+    this.type = "text";
+    this.value = "";
+    this.placeholder = "";
+    this.autocomplete = "";
+    this.hint = "";
+    this.info = "";
+    this.error = "";
+    this.required = false;
+    this.disabled = false;
+  }
+
+  protected override create(root: HTMLElement) {
+    this.#input.addEventListener("input", () => {
+      this.value = this.#input.value;
+    });
+    root.append(this.#info.heading, this.#input, this.#hint, this.#error);
+  }
+
+  protected override update() {
+    const input = this.#input;
+
+    const described = [
+      this.hint ? this.#hint.id : "",
+      this.error ? this.#error.id : "",
+    ]
+      .join(" ")
+      .trim();
+
+    this.#label.textContent = this.label;
+    this.#info.update(this.label, this.info);
+    input.type = this.type;
+    setAttribute(input, "name", this.name || null);
+    setAttribute(input, "placeholder", this.placeholder || null);
+    setAttribute(input, "autocomplete", this.autocomplete || null);
+    setAttribute(input, "aria-invalid", this.error ? "true" : null);
+    setAttribute(input, "aria-describedby", described || null);
+    input.required = this.required;
+    input.disabled = this.disabled;
+
+    if (input.value !== this.value) input.value = this.value;
+
+    this.#hint.textContent = this.hint;
+    this.#hint.hidden = !this.hint;
+    this.#error.textContent = this.error;
+    this.#error.hidden = !this.error;
+  }
+}
+
+GwInput.define("gw-input");
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "gw-input": GwInput;
+  }
+}