@timmo001/groundwork-ui 0.0.0-stage → 0.0.0

package/src/gw-dialog.ts

@@ -0,0 +1,246 @@
+/**
+ * `gw-dialog`: a modal on the native `<dialog>`, for what blocks the whole app.
+ * Docs: https://groundwork.timmo.dev/components/overlays/#dialog
+ *
+ * @module
+ */
+import { Dismissal, dismissalStyles } from "./dismiss.js";
+import { GwElement, css, h } from "./element.js";
+import "./gw-button.js";
+import { base } from "./styles.js";
+
+// MDI's close
+const closeIcon =
+  "M19,6.41L17.59,5L12,10.59L6.41,5L5,6.41L10.59,12L5,17.59L6.41,19L12,13.41L17.59,19L19,17.59L13.41,12L19,6.41Z";
+
+/**
+ * A modal on the native `<dialog>`, so focus is trapped and returned, Esc
+ * closes it and the page behind is inert. Open it with `show()`. Put buttons
+ * in the `actions` slot; a click on one with a `value` closes the dialog with
+ * that value, and fires `close`.
+ *
+ * @element gw-dialog
+ * @summary A modal for what blocks the whole app.
+ *
+ * @attr {string} heading - The heading beside the close button.
+ * @attr {boolean} open - Whether it shows.
+ *
+ * @slot - The content.
+ * @slot actions - Buttons; one with a `value` closes it with that value.
+ *
+ * @fires close - When it closes; `returnValue` holds the button's value.
+ */
+export class GwDialog extends GwElement {
+  static override properties = {
+    heading: {},
+    open: { type: "boolean", reflect: true },
+  } as const;
+
+  static override styles = [
+    base,
+    dismissalStyles,
+    css`
+      dialog {
+        width: min(32rem, calc(100vw - 2 * var(--gw-space-3)));
+        padding: 0;
+        color: var(--gw-color-text-primary);
+        background: var(--gw-color-surface-overlay);
+        border: var(--gw-border-width) solid var(--gw-color-border-normal);
+        border-radius: var(--gw-radius-panel);
+        box-shadow: var(--gw-shadow-l);
+      }
+
+      dialog::backdrop {
+        background: rgb(0 0 0 / 50%);
+      }
+
+      /* Fades and lifts in and out, the backdrop with it */
+      dialog,
+      dialog::backdrop {
+        transition:
+          opacity var(--gw-motion-normal) var(--gw-motion-easing),
+          scale var(--gw-motion-normal) var(--gw-motion-easing),
+          display var(--gw-motion-normal) allow-discrete,
+          overlay var(--gw-motion-normal) allow-discrete;
+      }
+
+      dialog,
+      dialog::backdrop {
+        opacity: 0;
+      }
+
+      dialog {
+        scale: 0.96;
+      }
+
+      dialog[open],
+      dialog[open]::backdrop {
+        opacity: 1;
+      }
+
+      dialog[open] {
+        scale: 1;
+      }
+
+      @starting-style {
+        dialog[open],
+        dialog[open]::backdrop {
+          opacity: 0;
+        }
+
+        dialog[open] {
+          scale: 0.96;
+        }
+      }
+
+      header {
+        display: flex;
+        gap: var(--gw-space-2);
+        align-items: center;
+        padding: var(--gw-space-3) var(--gw-space-3) 0 var(--gw-space-4);
+      }
+
+      h2 {
+        flex: 1;
+        margin: 0;
+        font-size: var(--gw-font-size-l);
+        font-weight: var(--gw-font-weight-strong);
+        color: var(--gw-color-text-strong);
+      }
+
+      .body {
+        padding: var(--gw-space-3) var(--gw-space-4);
+        font-size: var(--gw-font-size-s);
+      }
+
+      footer {
+        display: flex;
+        flex-wrap: wrap;
+        gap: var(--gw-space-1);
+        justify-content: flex-end;
+        padding: 0 var(--gw-space-4) var(--gw-space-4);
+      }
+
+      dialog > .discard {
+        padding: var(--gw-space-4);
+      }
+    `,
+  ];
+
+  declare heading: string;
+  declare open: boolean;
+
+  /** The value of the action that closed the dialog, or "" for Esc. */
+  returnValue = "";
+
+  constructor() {
+    super();
+    this.heading = "";
+    this.open = false;
+  }
+
+  readonly #heading = h("h2", { id: "heading" });
+
+  readonly #footer = h("footer", {}, h("slot", { name: "actions" }));
+
+  readonly #closeButton = h(
+    "gw-button",
+    {
+      class: "close",
+      variant: "neutral",
+      appearance: "plain",
+      size: "small",
+      labels: "hide",
+      icon: closeIcon,
+    },
+    "Close",
+  );
+
+  readonly #dialog = h(
+    "dialog",
+    { "aria-labelledby": "heading" },
+    h("header", {}, this.#heading, this.#closeButton),
+    h("div", { class: "body" }, h("slot")),
+    this.#footer,
+  );
+
+  readonly #dismissal = new Dismissal(this, this.#dialog, () => this.close());
+
+  /** Whether its content has changed since it opened, so closing it asks first. */
+  get dirty() {
+    return this.#dismissal.dirty;
+  }
+
+  set dirty(dirty: boolean) {
+    this.#dismissal.mark(dirty);
+  }
+
+  show() {
+    this.#dismissal.reset();
+    this.open = true;
+  }
+
+  close(value = "") {
+    this.returnValue = value;
+    this.open = false;
+  }
+
+  readonly #onAction = (event: Event) => {
+    const target = event.target;
+
+    if (target instanceof HTMLElement && target.hasAttribute("value")) {
+      this.close(target.getAttribute("value") ?? "");
+    }
+  };
+
+  readonly #onClose = () => {
+    this.open = false;
+    this.dispatchEvent(new Event("close", { bubbles: true, composed: true }));
+  };
+
+  // Esc and the close button close it at once while nothing has changed,
+  // and ask first once something has
+  readonly #onCancel = (event: Event) => {
+    event.preventDefault();
+    this.#dismissal.request();
+  };
+
+  // A click on the backdrop closes it too, but only while nothing has
+  // changed, so a stray click never throws work away
+  readonly #onBackdrop = (event: MouseEvent) => {
+    if (event.target === this.#dialog && !this.#dismissal.dirty) this.close();
+  };
+
+  protected override create(root: ShadowRoot) {
+    this.#dialog.addEventListener("close", this.#onClose);
+    this.#dialog.addEventListener("cancel", this.#onCancel);
+    this.#dialog.addEventListener("click", this.#onBackdrop);
+    this.#closeButton.addEventListener("click", () => {
+      this.#dismissal.request();
+    });
+    this.#footer.addEventListener("click", this.#onAction);
+    root.append(this.#dialog);
+  }
+
+  protected override update() {
+    const dialog = this.#dialog;
+
+    this.#heading.textContent = this.heading;
+
+    if (this.open && !dialog.open) {
+      dialog.showModal();
+      // Toasts rise back above it
+      document.dispatchEvent(new Event("gw-dialog-open"));
+    }
+
+    if (!this.open && dialog.open) dialog.close(this.returnValue);
+  }
+}
+
+GwDialog.define("gw-dialog");
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "gw-dialog": GwDialog;
+  }
+}

package/src/gw-dot.ts

@@ -0,0 +1,89 @@
+/**
+ * `gw-dot`: a small status dot.
+ * Docs: https://groundwork.timmo.dev/components/display/#chip-and-dot
+ *
+ * @module
+ */
+import { GwElement, css, h } from "./element.js";
+import { base, type Tone } from "./styles.js";
+
+/**
+ * A small status dot. Give it a `label`, such as "Online", unless text
+ * beside it already says the same.
+ *
+ * @element gw-dot
+ * @summary A small status dot.
+ *
+ * @attr {"neutral"|"accent"|"info"|"success"|"warning"|"danger"|"important"} tone - The color. Defaults to `neutral`.
+ * @attr {string} label - What it means, for assistive technology.
+ * @attr {boolean} pulse - Pulses, for something live.
+ */
+export class GwDot extends GwElement {
+  static override properties = {
+    tone: { reflect: true },
+    label: {},
+    pulse: { type: "boolean", reflect: true },
+  } as const;
+
+  static override styles = [
+    base,
+    css`
+      :host {
+        display: inline-block;
+        flex: none;
+        width: 0.5rem;
+        height: 0.5rem;
+        background: var(--gw-tone, var(--gw-color-text-secondary));
+        border-radius: 50%;
+      }
+
+      :host([pulse]) {
+        animation: pulse 1.6s ease-in-out infinite;
+      }
+
+      @keyframes pulse {
+        50% {
+          opacity: 0.4;
+        }
+      }
+
+      span {
+        position: absolute;
+        width: 1px;
+        height: 1px;
+        overflow: hidden;
+        clip-path: inset(50%);
+      }
+    `,
+  ];
+
+  declare tone: Tone;
+  declare label: string;
+  declare pulse: boolean;
+
+  readonly #label = h("span");
+
+  constructor() {
+    super();
+    this.tone = "neutral";
+    this.label = "";
+    this.pulse = false;
+  }
+
+  protected override create(root: ShadowRoot) {
+    root.append(this.#label);
+  }
+
+  protected override update() {
+    this.#label.textContent = this.label;
+    this.#label.hidden = !this.label;
+  }
+}
+
+GwDot.define("gw-dot");
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "gw-dot": GwDot;
+  }
+}

package/src/gw-empty-state.ts

@@ -0,0 +1,107 @@
+/**
+ * `gw-empty-state`: what a list or page shows when there's nothing in it.
+ * Docs: https://groundwork.timmo.dev/components/feedback/#empty-state
+ *
+ * @module
+ */
+import { GwElement, css, h } from "./element.js";
+import { base, createIcon, setIconPath } from "./styles.js";
+
+/**
+ * What a list or page shows when there's nothing in it, or nothing to do:
+ * an icon, a heading, a line of text and an optional action.
+ *
+ * @element gw-empty-state
+ * @summary What a list or page shows when there's nothing in it.
+ *
+ * @attr {string} icon - SVG path data for the icon.
+ * @attr {string} heading - The heading.
+ *
+ * @slot - A line of text.
+ * @slot actions - An action, such as adding the first item.
+ *
+ * @csspart empty - The block.
+ */
+export class GwEmptyState extends GwElement {
+  static override properties = {
+    icon: {},
+    heading: {},
+  } as const;
+
+  static override styles = [
+    base,
+    css`
+      :host {
+        display: block;
+      }
+
+      .empty {
+        display: flex;
+        flex-direction: column;
+        gap: var(--gw-space-1);
+        align-items: center;
+        justify-content: center;
+        padding: var(--gw-space-12) var(--gw-space-3);
+        color: var(--gw-color-text-secondary);
+        text-align: center;
+        --gw-icon-size: 2.5rem;
+      }
+
+      h2 {
+        margin: 0;
+        font-size: var(--gw-font-size-m);
+        font-weight: var(--gw-font-weight-strong);
+        color: var(--gw-color-text-strong);
+      }
+
+      ::slotted(p) {
+        margin: 0;
+      }
+
+      ::slotted([slot="actions"]) {
+        margin-block-start: var(--gw-space-2);
+      }
+    `,
+  ];
+
+  declare icon: string;
+  declare heading: string;
+
+  readonly #icon = createIcon("");
+
+  readonly #heading = h("h2");
+
+  constructor() {
+    super();
+    this.icon = "";
+    this.heading = "";
+  }
+
+  protected override create(root: ShadowRoot) {
+    root.append(
+      h(
+        "div",
+        { class: "empty", part: "empty" },
+        this.#icon,
+        this.#heading,
+        h("slot"),
+        h("slot", { name: "actions" }),
+      ),
+    );
+  }
+
+  protected override update() {
+    setIconPath(this.#icon, this.icon);
+    this.#icon.toggleAttribute("hidden", !this.icon);
+    this.#heading.textContent = this.heading;
+    this.#heading.hidden = !this.heading;
+  }
+}
+
+GwEmptyState.define("gw-empty-state");
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "gw-empty-state": GwEmptyState;
+  }
+}

package/src/gw-expansion.ts

@@ -0,0 +1,224 @@
+/**
+ * `gw-expansion`: a heading that opens and closes the content under it.
+ * Docs: https://groundwork.timmo.dev/components/display/#expansion-panel
+ *
+ * @module
+ */
+import { GwElement, css, h } from "./element.js";
+import { base } from "./styles.js";
+
+/**
+ * A heading that opens and closes the content under it, on a native
+ * `<details>`, so find-in-page and the keyboard work as they do anywhere. The
+ * content glides open and shut rather than jumping, and the chevron turns
+ * with it. `open` reflects its state and it fires `toggle`.
+ *
+ * @element gw-expansion
+ * @summary A heading that opens and closes the content under it.
+ *
+ * @attr {string} heading - The heading in the summary row.
+ * @attr {string} description - A line under the heading.
+ * @attr {boolean} open - Whether the content shows.
+ *
+ * @slot - The content.
+ * @slot icon - An icon before the heading.
+ *
+ * @csspart details - The native `<details>`.
+ * @csspart summary - The summary row.
+ * @csspart content - The content's wrapper.
+ *
+ * @fires toggle - When it opens or closes.
+ */
+export class GwExpansion extends GwElement {
+  static override properties = {
+    heading: {},
+    description: {},
+    open: { type: "boolean", reflect: true },
+  } as const;
+
+  static override styles = [
+    base,
+    css`
+      :host {
+        display: block;
+        interpolate-size: allow-keywords;
+      }
+
+      details {
+        background: var(--gw-color-surface-raised);
+        border: var(--gw-border-width) solid var(--gw-color-border-normal);
+        border-radius: var(--gw-radius-panel);
+      }
+
+      details::details-content {
+        block-size: 0;
+        overflow: clip;
+        transition:
+          block-size var(--gw-motion-normal) var(--gw-motion-easing),
+          content-visibility var(--gw-motion-normal) allow-discrete;
+      }
+
+      details[open]::details-content {
+        block-size: auto;
+      }
+
+      summary {
+        display: flex;
+        gap: var(--gw-space-3);
+        align-items: center;
+        min-height: 3rem;
+        padding: var(--gw-space-2) var(--gw-space-4);
+        cursor: pointer;
+        list-style: none;
+        border-radius: calc(var(--gw-radius-panel) - var(--gw-border-width));
+        user-select: none;
+        transition:
+          background-color var(--gw-motion-fast) var(--gw-motion-easing),
+          border-radius var(--gw-motion-normal) var(--gw-motion-easing);
+      }
+
+      summary::-webkit-details-marker {
+        display: none;
+      }
+
+      details[open] summary {
+        border-end-start-radius: 0;
+        border-end-end-radius: 0;
+      }
+
+      summary:hover {
+        background: var(--gw-color-fill-neutral-hovered);
+      }
+
+      summary:active {
+        background: var(--gw-color-fill-neutral-pressed);
+      }
+
+      summary:focus-visible {
+        outline: var(--gw-focus-width) solid var(--gw-color-focus);
+        outline-offset: var(--gw-focus-offset);
+      }
+
+      .text {
+        display: flex;
+        flex: 1;
+        flex-direction: column;
+        gap: var(--gw-space-0-5);
+      }
+
+      .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);
+      }
+
+      /* The chevron sits in a round neutral button, so the heading reads as
+         something to press */
+      .toggle {
+        display: grid;
+        flex: none;
+        place-items: center;
+        width: 2rem;
+        height: 2rem;
+        background: var(--gw-color-fill-neutral-resting);
+        border-radius: 50%;
+        transition: background-color var(--gw-motion-fast)
+          var(--gw-motion-easing);
+      }
+
+      summary:hover .toggle {
+        background: var(--gw-color-fill-neutral-pressed);
+      }
+
+      summary:active .toggle {
+        background: var(--gw-color-fill-neutral-selected);
+      }
+
+      .chevron {
+        width: 0.45rem;
+        height: 0.45rem;
+        border-inline-end: 1.5px solid var(--gw-color-text-primary);
+        border-block-end: 1.5px solid var(--gw-color-text-primary);
+        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);
+      }
+
+      details[open] .chevron {
+        rotate: 225deg;
+        translate: 0 0.125rem;
+      }
+
+      .content {
+        padding: var(--gw-space-3) var(--gw-space-4) var(--gw-space-4);
+        border-block-start: var(--gw-border-width) solid
+          var(--gw-color-border-quiet);
+        font-size: var(--gw-font-size-s);
+      }
+    `,
+  ];
+
+  declare heading: string;
+  declare description: string;
+  declare open: boolean;
+
+  readonly #heading = h("span", { class: "heading" });
+
+  readonly #description = h("span", { class: "description" });
+
+  readonly #details = h(
+    "details",
+    { part: "details" },
+    h(
+      "summary",
+      { part: "summary" },
+      h("slot", { name: "icon" }),
+      h("span", { class: "text" }, this.#heading, this.#description),
+      h(
+        "span",
+        { class: "toggle", "aria-hidden": "true" },
+        h("span", { class: "chevron" }),
+      ),
+    ),
+    h("div", { class: "content", part: "content" }, h("slot")),
+  );
+
+  constructor() {
+    super();
+    this.heading = "";
+    this.description = "";
+    this.open = false;
+  }
+
+  readonly #onToggle = () => {
+    this.open = this.#details.open;
+    this.dispatchEvent(new Event("toggle", { bubbles: true, composed: true }));
+  };
+
+  protected override create(root: ShadowRoot) {
+    this.#details.addEventListener("toggle", this.#onToggle);
+    root.append(this.#details);
+  }
+
+  protected override update() {
+    this.#details.open = this.open;
+    this.#heading.textContent = this.heading;
+    this.#description.textContent = this.description;
+    this.#description.hidden = !this.description;
+  }
+}
+
+GwExpansion.define("gw-expansion");
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "gw-expansion": GwExpansion;
+  }
+}