@timmo001/groundwork-ui 0.0.0-stage → 0.3.0

package/src/gw-setting-row.ts

@@ -0,0 +1,168 @@
+/**
+ * `gw-setting-row`: a setting's name and description beside its control.
+ * Docs: https://groundwork.timmo.dev/components/inputs/#setting-row
+ *
+ * @module
+ */
+import { GwElement, css, h, setAttribute } from "./element.js";
+import "./gw-skeleton.js";
+import { fadeIn } from "./motion.js";
+import { base } from "./styles.js";
+
+/**
+ * A setting: its name and description on one side, its control on the
+ * other. A wide control drops under the text when there isn't room. Rows
+ * after the first in their parent get a line above them. While `loading`, a
+ * skeleton stands in for the control, and for the text until it's known.
+ *
+ * @element gw-setting-row
+ * @summary A setting's name and description beside its control.
+ *
+ * @attr {string} heading - The setting's name.
+ * @attr {string} description - What it does.
+ * @attr {boolean} loading - Shows skeletons for the control and any unknown text.
+ *
+ * @slot - The control.
+ *
+ * @csspart row - The row.
+ *
+ * @cssprop --gw-row-padding - The padding above and below. Defaults to `--gw-space-2`.
+ */
+export class GwSettingRow extends GwElement {
+  static override properties = {
+    heading: {},
+    description: {},
+    loading: { type: "boolean", reflect: true },
+  } as const;
+
+  static override styles = [
+    base,
+    css`
+      :host {
+        display: block;
+      }
+
+      .row {
+        display: flex;
+        flex-wrap: wrap;
+        gap: var(--gw-space-1) var(--gw-space-3);
+        align-items: center;
+        justify-content: space-between;
+        padding: var(--gw-row-padding, var(--gw-space-2)) 0;
+      }
+
+      /* A full line even in themes without borders, since it separates rows */
+      :host(:not(:first-of-type)) .row {
+        border-block-start: max(var(--gw-border-width), 1px) solid
+          var(--gw-color-border-quiet);
+      }
+
+      .text {
+        flex: 1 1 12rem;
+        min-width: 0;
+      }
+
+      .heading {
+        font-size: var(--gw-font-size-s);
+        font-weight: var(--gw-font-weight-strong);
+        color: var(--gw-color-text-strong);
+      }
+
+      .description {
+        font-size: var(--gw-font-size-xs);
+        color: var(--gw-color-text-secondary);
+      }
+
+      .control {
+        max-width: 100%;
+      }
+
+      .control-skeleton {
+        width: 3.25rem;
+        min-height: 0;
+        height: 2rem;
+        --gw-skeleton-radius: var(--gw-radius-pill);
+      }
+    `,
+  ];
+
+  declare heading: string;
+  declare description: string;
+  declare loading: boolean;
+
+  readonly #row = h("div", { class: "row", part: "row" });
+
+  readonly #heading = h("span");
+
+  readonly #headingSkeleton = h("gw-skeleton-text", {
+    style: "--gw-skeleton-width: 8rem",
+  });
+
+  readonly #description = h("div", { class: "description" });
+
+  readonly #descriptionSkeleton = h(
+    "div",
+    { class: "description" },
+    h("gw-skeleton-text", { style: "--gw-skeleton-width: 12rem" }),
+  );
+
+  readonly #slot = h("slot");
+
+  readonly #controlSkeleton = h("gw-skeleton", { class: "control-skeleton" });
+
+  readonly #control = h(
+    "div",
+    { class: "control" },
+    this.#controlSkeleton,
+    this.#slot,
+  );
+
+  #rendered = false;
+
+  constructor() {
+    super();
+    this.heading = "";
+    this.description = "";
+    this.loading = false;
+  }
+
+  protected override create(root: ShadowRoot) {
+    this.#row.append(
+      h(
+        "div",
+        { class: "text" },
+        h("div", { class: "heading" }, this.#heading, this.#headingSkeleton),
+        this.#description,
+        this.#descriptionSkeleton,
+      ),
+      this.#control,
+    );
+    root.append(this.#row);
+  }
+
+  protected override update(changed: ReadonlySet<string>) {
+    setAttribute(this.#row, "aria-busy", this.loading ? "true" : null);
+    this.#heading.textContent = this.heading;
+    this.#headingSkeleton.hidden = !this.loading || this.heading !== "";
+    this.#description.textContent = this.description;
+    this.#description.hidden = !this.description;
+    this.#descriptionSkeleton.hidden =
+      !this.loading || this.heading !== "" || this.description !== "";
+    this.#controlSkeleton.hidden = !this.loading;
+    this.#slot.hidden = this.loading;
+
+    if (this.#rendered && changed.has("loading") && !this.loading) {
+      fadeIn(this.#control);
+    }
+
+    this.#rendered = true;
+  }
+}
+
+GwSettingRow.define("gw-setting-row");
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "gw-setting-row": GwSettingRow;
+  }
+}

package/src/gw-skeleton.ts

@@ -0,0 +1,178 @@
+/**
+ * `gw-skeleton` and its text, lines and icon shapes: placeholders for what's
+ * loading.
+ * Docs: https://groundwork.timmo.dev/components/feedback/#loading
+ *
+ * @module
+ */
+import { GwElement, css, h } from "./element.js";
+import { base } from "./styles.js";
+
+/**
+ * A placeholder for what's loading, sized by its container or by `width`
+ * and `height` in CSS. The shapes below extend it, and components with a
+ * `loading` attribute draw their own from them, so a spinner is only needed
+ * for an action in progress. It's hidden from assistive technology, so mark
+ * the region it sits in `aria-busy`.
+ *
+ * @element gw-skeleton
+ * @summary A pulsing placeholder for what's loading.
+ *
+ * @cssprop --gw-skeleton-color - The fill. Defaults to the neutral fill.
+ * @cssprop --gw-skeleton-radius - The corners. Defaults to the control radius.
+ */
+export class GwSkeleton extends GwElement {
+  static override styles: readonly CSSStyleSheet[] = [
+    base,
+    css`
+      :host {
+        display: block;
+        min-height: 1rem;
+        background: var(
+          --gw-skeleton-color,
+          var(--gw-color-fill-neutral-resting)
+        );
+        border-radius: var(--gw-skeleton-radius, var(--gw-radius-control));
+        animation: pulse 2s ease-in-out infinite;
+      }
+
+      @keyframes pulse {
+        50% {
+          opacity: 0.45;
+        }
+      }
+
+      @media (forced-colors: active) {
+        :host {
+          background: GrayText;
+        }
+      }
+    `,
+  ];
+
+  override connectedCallback() {
+    super.connectedCallback();
+    this.setAttribute("aria-hidden", "true");
+  }
+}
+
+/**
+ * A line of text. Its height follows the font size around it, so it lines up
+ * with the text it stands in for.
+ *
+ * @element gw-skeleton-text
+ * @summary A placeholder for a line of text.
+ *
+ * @cssprop --gw-skeleton-width - Defaults to `8rem`.
+ */
+export class GwSkeletonText extends GwSkeleton {
+  static override styles = [
+    ...GwSkeleton.styles,
+    css`
+      :host {
+        display: inline-block;
+        width: var(--gw-skeleton-width, 8rem);
+        max-width: 100%;
+        height: 1em;
+        min-height: 0;
+        vertical-align: middle;
+      }
+    `,
+  ];
+}
+
+/**
+ * Several lines of text, as a paragraph, with a shorter last line so it
+ * doesn't read as a solid block.
+ *
+ * @element gw-skeleton-lines
+ * @summary A placeholder for a paragraph.
+ *
+ * @attr {number} lines - How many lines. Defaults to 3.
+ */
+export class GwSkeletonLines extends GwElement {
+  static override properties = {
+    lines: { type: "number" },
+  } as const;
+
+  static override styles = [
+    base,
+    css`
+      :host {
+        display: flex;
+        flex-direction: column;
+        gap: 0.5em;
+      }
+
+      gw-skeleton-text {
+        --gw-skeleton-width: 100%;
+      }
+
+      gw-skeleton-text:last-child:not(:first-child) {
+        --gw-skeleton-width: 60%;
+      }
+    `,
+  ];
+
+  declare lines: number;
+
+  constructor() {
+    super();
+    this.lines = 3;
+  }
+
+  override connectedCallback() {
+    super.connectedCallback();
+    this.setAttribute("aria-hidden", "true");
+  }
+
+  protected override update() {
+    this.renderRoot.replaceChildren(
+      ...Array.from({ length: Math.max(1, this.lines || 1) }, () =>
+        h("gw-skeleton-text"),
+      ),
+    );
+  }
+}
+
+/**
+ * A round placeholder for an icon or avatar.
+ *
+ * @element gw-skeleton-icon
+ * @summary A round placeholder for an icon or avatar.
+ *
+ * @cssprop --gw-icon-size - Its size. Defaults to `1.25rem`.
+ */
+export class GwSkeletonIcon extends GwSkeleton {
+  static override styles = [
+    ...GwSkeleton.styles,
+    css`
+      :host {
+        display: inline-block;
+        flex: none;
+        width: var(--gw-icon-size, 1.25rem);
+        height: var(--gw-icon-size, 1.25rem);
+        min-height: 0;
+        vertical-align: middle;
+        border-radius: var(--gw-radius-pill);
+      }
+    `,
+  ];
+}
+
+GwSkeleton.define("gw-skeleton");
+
+GwSkeletonText.define("gw-skeleton-text");
+
+GwSkeletonLines.define("gw-skeleton-lines");
+
+GwSkeletonIcon.define("gw-skeleton-icon");
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "gw-skeleton": GwSkeleton;
+    "gw-skeleton-text": GwSkeletonText;
+    "gw-skeleton-lines": GwSkeletonLines;
+    "gw-skeleton-icon": GwSkeletonIcon;
+  }
+}

package/src/gw-spinner.ts

@@ -0,0 +1,84 @@
+/**
+ * `gw-spinner`: a spinning ring, for waits a skeleton can't stand in for.
+ * Docs: https://groundwork.timmo.dev/components/feedback/#spinner
+ *
+ * @module
+ */
+import { GwElement, css, h } from "./element.js";
+import { base } from "./styles.js";
+
+/**
+ * A spinning ring while something loads, announced by its `label`.
+ *
+ * @element gw-spinner
+ * @summary A spinning ring for a wait a skeleton can't stand in for.
+ *
+ * @attr {string} label - What's loading, for assistive technology. Defaults to `Loading`.
+ *
+ * @cssprop --gw-spinner-size - The ring's size. Defaults to `1.25rem`.
+ */
+export class GwSpinner extends GwElement {
+  static override properties = {
+    label: {},
+  } as const;
+
+  static override styles = [
+    base,
+    css`
+      :host {
+        display: inline-flex;
+        width: var(--gw-spinner-size, 1.25rem);
+        height: var(--gw-spinner-size, 1.25rem);
+        color: var(--gw-color-accent);
+      }
+
+      .ring {
+        width: 100%;
+        height: 100%;
+        border: 2px solid var(--gw-color-border-quiet);
+        border-top-color: currentColor;
+        border-radius: 50%;
+        animation: spin 0.9s linear infinite;
+      }
+
+      @keyframes spin {
+        to {
+          transform: rotate(360deg);
+        }
+      }
+
+      .label {
+        position: absolute;
+        width: 1px;
+        height: 1px;
+        overflow: hidden;
+        clip-path: inset(50%);
+      }
+    `,
+  ];
+
+  declare label: string;
+
+  readonly #label = h("span", { class: "label" });
+
+  constructor() {
+    super();
+    this.label = "Loading";
+  }
+
+  protected override create(root: ShadowRoot) {
+    root.append(h("span", { class: "ring", role: "status" }, this.#label));
+  }
+
+  protected override update() {
+    this.#label.textContent = this.label;
+  }
+}
+
+GwSpinner.define("gw-spinner");
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "gw-spinner": GwSpinner;
+  }
+}

package/src/gw-toast.ts

@@ -0,0 +1,167 @@
+/**
+ * `gw-toaster`: brief, non-interactive toasts in the bottom end corner.
+ * Docs: https://groundwork.timmo.dev/components/feedback/#toast
+ *
+ * @module
+ */
+import { GwElement, css, h } from "./element.js";
+import { fadeEasing, motionDuration, reducedMotion } from "./motion.js";
+import { base, type Tone } from "./styles.js";
+
+/**
+ * Where toasts appear: the bottom corner on the end side, away from what
+ * people click. Call `show(message, tone)`; each toast is announced politely
+ * and fades out after `duration` milliseconds.
+ *
+ * A toast only tells; it has no actions and lets every click through, since
+ * it may sit over something interactive and leaves before it can be used.
+ * It's in the top layer and rises above any dialog each time one shows. It's
+ * a last resort: show an outcome where it happened instead.
+ *
+ * @element gw-toaster
+ * @summary Brief, non-interactive toasts in the bottom end corner.
+ *
+ * @attr {number} duration - Milliseconds each toast shows for. Defaults to 5000.
+ */
+export class GwToaster extends GwElement {
+  static override properties = {
+    duration: { type: "number" },
+  } as const;
+
+  static override styles = [
+    base,
+    css`
+      :host {
+        position: fixed;
+        inset: auto var(--gw-space-4) var(--gw-space-4) auto;
+        width: min(22rem, calc(100vw - 2 * var(--gw-space-4)));
+        padding: 0;
+        margin: 0;
+        overflow: visible;
+        color: inherit;
+        pointer-events: none;
+        user-select: none;
+        background: none;
+        border: 0;
+      }
+
+      :host(:dir(rtl)) {
+        inset: auto auto var(--gw-space-4) var(--gw-space-4);
+      }
+
+      :host(:not(:popover-open)) {
+        display: none;
+      }
+
+      .list {
+        display: flex;
+        flex-direction: column;
+        gap: var(--gw-space-1);
+        align-items: flex-end;
+      }
+
+      .toast {
+        max-width: 100%;
+        padding: var(--gw-space-2) var(--gw-space-3);
+        font-size: var(--gw-font-size-s);
+        color: var(--gw-color-text-strong);
+        background: var(--gw-color-surface-overlay);
+        border: var(--gw-border-width) solid var(--gw-color-border-normal);
+        border-inline-start: calc(var(--gw-border-width) * 4) solid
+          var(--gw-toast-tone);
+        border-radius: var(--gw-radius-control);
+        box-shadow: var(--gw-shadow-m);
+      }
+    `,
+  ];
+
+  declare duration: number;
+
+  readonly #list = h("div", {
+    class: "list",
+    role: "status",
+    "aria-live": "polite",
+  });
+
+  constructor() {
+    super();
+    this.duration = 5000;
+  }
+
+  override connectedCallback() {
+    this.setAttribute("popover", "manual");
+    super.connectedCallback();
+    document.addEventListener("gw-dialog-open", this.#onDialogOpen);
+    // It stays open while empty, as nothing in it can be clicked, so the
+    // live region is in place before a message arrives.
+    this.#raise();
+  }
+
+  override disconnectedCallback() {
+    super.disconnectedCallback();
+    document.removeEventListener("gw-dialog-open", this.#onDialogOpen);
+  }
+
+  readonly #onDialogOpen = () => {
+    if (this.#list.childElementCount > 0) this.#raise();
+  };
+
+  protected override create(root: ShadowRoot) {
+    root.append(this.#list);
+  }
+
+  show(message: string, tone: Tone = "neutral") {
+    const toast = h("div", { class: "toast" }, message);
+
+    toast.style.setProperty(
+      "--gw-toast-tone",
+      tone === "neutral"
+        ? "var(--gw-color-border-loud)"
+        : `var(--gw-color-${tone})`,
+    );
+    this.#raise();
+    this.#list.append(toast);
+
+    const reduced = reducedMotion();
+    const slow = motionDuration(this, "--gw-motion-slow", 350);
+
+    toast.animate(
+      [
+        { opacity: 0, translate: "0 0.5rem" },
+        { opacity: 1, translate: "0 0" },
+      ],
+      { duration: reduced ? 0 : slow, easing: fadeEasing },
+    );
+
+    setTimeout(() => {
+      const leave = toast.animate([{ opacity: 1 }, { opacity: 0 }], {
+        duration: reduced ? 0 : slow,
+        easing: fadeEasing,
+        fill: "forwards",
+      });
+
+      leave.addEventListener("finish", () => toast.remove());
+      leave.addEventListener("cancel", () => toast.remove());
+    }, this.duration);
+  }
+
+  /**
+   * Puts the toaster on top of the top layer, above any dialog opened since
+   * it last showed.
+   */
+  #raise() {
+    if (!this.isConnected) return;
+
+    if (this.matches(":popover-open")) this.hidePopover();
+
+    this.showPopover();
+  }
+}
+
+GwToaster.define("gw-toaster");
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "gw-toaster": GwToaster;
+  }
+}

package/src/index.ts

@@ -0,0 +1,76 @@
+/**
+ * Groundwork's web components: framework-free custom elements styled by the
+ * `--gw-*` tokens. Importing this defines every `gw-` element.
+ * Docs: https://groundwork.timmo.dev/components
+ *
+ * @packageDocumentation
+ */
+export * from "./element.js";
+
+export * from "./styles.js";
+
+export * from "./motion.js";
+
+export * from "./fields.js";
+
+export * from "./layout.js";
+
+export * from "./gw-alert.js";
+
+export * from "./gw-badge.js";
+
+export * from "./gw-banner.js";
+
+export * from "./gw-button.js";
+
+export * from "./gw-card.js";
+
+export * from "./gw-checkbox.js";
+
+export * from "./gw-chip.js";
+
+export * from "./gw-command-menu.js";
+
+export * from "./gw-dialog.js";
+
+export * from "./gw-dot.js";
+
+export * from "./gw-empty-state.js";
+
+export * from "./gw-expansion.js";
+
+export * from "./gw-facts.js";
+
+export * from "./gw-fade-in.js";
+
+export * from "./gw-gauge.js";
+
+export * from "./gw-input.js";
+
+export * from "./gw-menu-button.js";
+
+export * from "./gw-meter.js";
+
+export * from "./gw-notification.js";
+
+export * from "./gw-notification-center.js";
+
+export * from "./gw-option-list.js";
+
+export * from "./gw-page-header.js";
+
+export * from "./gw-popover.js";
+
+export * from "./gw-section-title.js";
+
+export * from "./gw-segmented.js";
+
+export * from "./gw-select.js";
+
+export * from "./gw-setting-row.js";
+
+export * from "./gw-skeleton.js";
+
+export * from "./gw-spinner.js";
+
+export * from "./gw-toast.js";