@timmo001/groundwork-ui 0.0.0-stage → 0.3.0

package/src/gw-card.ts

@@ -0,0 +1,187 @@
+/**
+ * `gw-card`: a surface for one group of content.
+ * Docs: https://groundwork.timmo.dev/components/display/#card
+ *
+ * @module
+ */
+import { GwElement, css, h, setAttribute } from "./element.js";
+import "./gw-skeleton.js";
+import { animateHeight, fadeIn } from "./motion.js";
+import { base } from "./styles.js";
+
+/**
+ * A surface for one group of content, with an optional heading and actions.
+ * With `href` the whole card is a link. While `loading`, lines of skeleton
+ * stand in for the content, and for the heading until it's known. The card
+ * glides to its new height and the content fades in once it's loaded.
+ *
+ * @element gw-card
+ * @summary A surface for one group of content, or a link to more.
+ *
+ * @attr {string} heading - The card's heading.
+ * @attr {string} href - Makes the whole card a link to this address.
+ * @attr {boolean} flush - Drops the padding, for content that runs to the edges.
+ * @attr {boolean} loading - Shows skeleton lines for the content and any unknown heading.
+ * @attr {number} lines - How many skeleton lines while loading. Defaults to 3.
+ *
+ * @slot - The content.
+ * @slot actions - Buttons beside the heading.
+ *
+ * @csspart card - The card's surface.
+ */
+export class GwCard extends GwElement {
+  static override properties = {
+    heading: {},
+    href: {},
+    flush: { type: "boolean", reflect: true },
+    loading: { type: "boolean", reflect: true },
+    lines: { type: "number" },
+  } as const;
+
+  static override styles = [
+    base,
+    css`
+      :host {
+        display: block;
+      }
+
+      .card {
+        display: flex;
+        flex-direction: column;
+        gap: var(--gw-space-3);
+        height: 100%;
+        padding: var(--gw-space-4);
+        color: inherit;
+        text-decoration: none;
+        background: var(--gw-color-surface-raised);
+        border: var(--gw-border-width) solid var(--gw-color-border-normal);
+        border-radius: var(--gw-radius-panel);
+        box-shadow: var(--gw-shadow-s);
+      }
+
+      :host([flush]) .card {
+        padding: 0;
+        overflow: hidden;
+      }
+
+      a.card {
+        transition: border-color var(--gw-motion-fast) var(--gw-motion-easing);
+      }
+
+      a.card:hover {
+        border-color: var(--gw-color-border-accent);
+      }
+
+      header {
+        display: flex;
+        gap: var(--gw-space-2);
+        align-items: center;
+      }
+
+      h2 {
+        flex: 1;
+        margin: 0;
+        font-size: var(--gw-font-size-m);
+        font-weight: var(--gw-font-weight-strong);
+        color: var(--gw-color-text-strong);
+      }
+
+      .body:not([hidden]) {
+        display: flex;
+        flex-direction: column;
+        gap: inherit;
+      }
+    `,
+  ];
+
+  declare heading: string;
+  declare href: string;
+  declare flush: boolean;
+  declare loading: boolean;
+  /** How many lines of skeleton stand in for the content while loading. */
+  declare lines: number;
+
+  readonly #title = h("span");
+
+  readonly #titleSkeleton = h("gw-skeleton-text");
+
+  readonly #header = h(
+    "header",
+    {},
+    h("h2", {}, this.#title, this.#titleSkeleton),
+    h("slot", { name: "actions" }),
+  );
+
+  readonly #skeleton = h("gw-skeleton-lines");
+
+  readonly #body = h("div", { class: "body" }, h("slot"));
+
+  #card: HTMLElement = h("section", { class: "card", part: "card" });
+
+  #wasLoading = false;
+
+  #rendered = false;
+
+  constructor() {
+    super();
+    this.heading = "";
+    this.href = "";
+    this.flush = false;
+    this.loading = false;
+    this.lines = 3;
+  }
+
+  protected override create(root: ShadowRoot) {
+    this.#card.append(this.#header, this.#skeleton, this.#body);
+    root.append(this.#card);
+  }
+
+  protected override update(changed: ReadonlySet<string>) {
+    const animate =
+      changed.has("loading") &&
+      this.#rendered &&
+      this.#wasLoading !== this.loading;
+
+    const before = animate ? this.offsetHeight : 0;
+
+    if (
+      changed.has("href") &&
+      (this.#card.tagName === "A") !== Boolean(this.href)
+    ) {
+      const next = this.href
+        ? h("a", { class: "card", part: "card" })
+        : h("section", { class: "card", part: "card" });
+
+      next.append(...this.#card.childNodes);
+      this.#card.replaceWith(next);
+      this.#card = next;
+    }
+
+    if (this.#card instanceof HTMLAnchorElement) this.#card.href = this.href;
+
+    setAttribute(this.#card, "aria-busy", this.loading ? "true" : null);
+    this.#title.textContent = this.heading;
+    this.#titleSkeleton.hidden = this.heading !== "" || !this.loading;
+    this.#header.hidden = !this.heading && !this.loading;
+    this.#skeleton.lines = this.lines;
+    this.#skeleton.hidden = !this.loading;
+    this.#body.hidden = this.loading;
+
+    if (animate) {
+      animateHeight(this, before);
+
+      if (!this.loading) fadeIn(this.#body);
+    }
+
+    this.#wasLoading = this.loading;
+    this.#rendered = true;
+  }
+}
+
+GwCard.define("gw-card");
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "gw-card": GwCard;
+  }
+}

package/src/gw-checkbox.ts

@@ -0,0 +1,113 @@
+/**
+ * `gw-checkbox` and `gw-switch`: labeled native checkboxes in light DOM.
+ * Docs: https://groundwork.timmo.dev/components/inputs/#checkbox-and-switch
+ *
+ * @module
+ */
+import { h, setAttribute } from "./element.js";
+import { LightElement, fieldId } from "./fields.js";
+
+/**
+ * A labeled native checkbox. `gw-switch` draws the same control as a switch.
+ *
+ * @element gw-checkbox
+ * @summary A labeled checkbox in light DOM, so forms see it.
+ *
+ * @attr {string} label - The label.
+ * @attr {string} name - The form field name.
+ * @attr {string} value - The value submitted when checked. Defaults to `on`.
+ * @attr {string} hint - One line of help under it.
+ * @attr {boolean} checked - Whether it's checked.
+ * @attr {boolean} disabled - Disables it.
+ * @attr {boolean} label-hidden - Hides the label but keeps it for assistive technology.
+ */
+export class GwCheckbox extends LightElement {
+  static override properties = {
+    label: {},
+    name: {},
+    value: {},
+    hint: {},
+    checked: { type: "boolean" },
+    disabled: { type: "boolean" },
+    labelHidden: { type: "boolean", attribute: "label-hidden" },
+  } as const;
+
+  declare label: string;
+  /** Keeps the label for assistive technology but hides it, such as in a setting row. */
+  declare labelHidden: boolean;
+  declare name: string;
+  declare value: string;
+  declare hint: string;
+  declare checked: boolean;
+  declare disabled: boolean;
+
+  readonly #id = fieldId();
+
+  readonly #input = h("input", { type: "checkbox" });
+
+  readonly #text = h("span");
+
+  readonly #hint = h("p", { class: "gw-hint", id: `${this.#id}-hint` });
+
+  /** `switch` for `gw-switch`, so assistive technology announces it as one. */
+  protected get controlRole(): string | undefined {
+    return undefined;
+  }
+
+  constructor() {
+    super();
+    this.label = "";
+    this.name = "";
+    this.value = "on";
+    this.hint = "";
+    this.checked = false;
+    this.disabled = false;
+    this.labelHidden = false;
+  }
+
+  protected override create(root: HTMLElement) {
+    setAttribute(this.#input, "role", this.controlRole);
+    this.#input.addEventListener("change", () => {
+      this.checked = this.#input.checked;
+    });
+    root.append(h("label", {}, this.#input, this.#text), this.#hint);
+  }
+
+  protected override update() {
+    const input = this.#input;
+
+    setAttribute(input, "name", this.name || null);
+    input.value = this.value;
+    setAttribute(input, "aria-describedby", this.hint ? this.#hint.id : null);
+    input.disabled = this.disabled;
+    input.checked = this.checked;
+    this.#text.textContent = this.label;
+    this.#text.className = this.labelHidden ? "gw-visually-hidden" : "";
+    this.#hint.textContent = this.hint;
+    this.#hint.hidden = !this.hint;
+  }
+}
+
+/**
+ * A checkbox drawn as a switch, announced as a switch. It takes the same
+ * attributes as `gw-checkbox`.
+ *
+ * @element gw-switch
+ * @summary A labeled switch for a setting that applies at once.
+ */
+export class GwSwitch extends GwCheckbox {
+  protected override get controlRole() {
+    return "switch";
+  }
+}
+
+GwCheckbox.define("gw-checkbox");
+
+GwSwitch.define("gw-switch");
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "gw-checkbox": GwCheckbox;
+    "gw-switch": GwSwitch;
+  }
+}

package/src/gw-chip.ts

@@ -0,0 +1,122 @@
+/**
+ * `gw-chip`: a short status or category, tinted by its tone.
+ * Docs: https://groundwork.timmo.dev/components/display/#chip-and-dot
+ *
+ * @module
+ */
+import { GwElement, css, h, setAttribute } from "./element.js";
+import "./gw-skeleton.js";
+import { fadeIn } from "./motion.js";
+import { base, createIcon, setIconPath, type Tone } from "./styles.js";
+
+/**
+ * A short status or category, tinted by its `tone`. While `loading`, a
+ * skeleton stands in for its text, and the text fades in once it's loaded.
+ *
+ * @element gw-chip
+ * @summary A short status or category, tinted by its tone.
+ *
+ * @attr {"neutral"|"accent"|"info"|"success"|"warning"|"danger"|"important"} tone - The tint. Defaults to `neutral`.
+ * @attr {string} icon - SVG path data for an icon before the text.
+ * @attr {boolean} loading - Shows a skeleton for the text.
+ *
+ * @slot - The text.
+ * @slot icon - An icon before the text, in place of `icon`.
+ *
+ * @csspart chip - The chip.
+ */
+export class GwChip extends GwElement {
+  static override properties = {
+    tone: { reflect: true },
+    icon: {},
+    loading: { type: "boolean", reflect: true },
+  } as const;
+
+  static override styles = [
+    base,
+    css`
+      :host {
+        display: inline-flex;
+      }
+
+      /* 32px, with 12px padding */
+      .chip {
+        display: inline-flex;
+        gap: var(--gw-space-2);
+        align-items: center;
+        box-sizing: border-box;
+        height: 2rem;
+        padding: 0 var(--gw-space-3);
+        font-size: var(--gw-font-size-xs);
+        font-weight: var(--gw-font-weight-strong);
+        color: var(--gw-color-text-strong);
+        background: var(--gw-tone-fill, var(--gw-color-fill-neutral-resting));
+        border: var(--gw-border-width) solid
+          var(--gw-tone-border, var(--gw-color-border-quiet));
+        border-radius: var(--gw-radius-chip);
+        --gw-icon-size: 1rem;
+      }
+
+      .content {
+        display: inline-flex;
+        gap: inherit;
+        align-items: center;
+      }
+    `,
+  ];
+
+  declare tone: Tone;
+  /** SVG path data for an icon before the text, instead of the `icon` slot. */
+  declare icon: string;
+  declare loading: boolean;
+
+  readonly #icon = createIcon("");
+
+  readonly #chip = h("span", { class: "chip", part: "chip" });
+
+  readonly #skeleton = h("gw-skeleton-text", {
+    style: "--gw-skeleton-width: 3.5rem",
+  });
+
+  readonly #content = h(
+    "span",
+    { class: "content" },
+    h("slot", { name: "icon" }, this.#icon),
+    h("slot"),
+  );
+
+  constructor() {
+    super();
+    this.tone = "neutral";
+    this.icon = "";
+    this.loading = false;
+  }
+
+  protected override create(root: ShadowRoot) {
+    this.#chip.append(this.#skeleton, this.#content);
+    root.append(this.#chip);
+  }
+
+  protected override update(changed: ReadonlySet<string>) {
+    const wasLoading = this.#content.hidden;
+
+    setIconPath(this.#icon, this.icon);
+    this.#icon.toggleAttribute("hidden", !this.icon);
+
+    setAttribute(this.#chip, "aria-busy", this.loading ? "true" : null);
+    this.#skeleton.hidden = !this.loading;
+    this.#content.hidden = this.loading;
+
+    if (changed.has("loading") && wasLoading && !this.loading) {
+      fadeIn(this.#content);
+    }
+  }
+}
+
+GwChip.define("gw-chip");
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "gw-chip": GwChip;
+  }
+}

package/src/gw-command-menu.ts

@@ -0,0 +1,283 @@
+/**
+ * `gw-command-menu`: a searchable list of commands on Cmd+K or Ctrl+K.
+ * Docs: https://groundwork.timmo.dev/components/overlays/#command-menu
+ *
+ * @module
+ */
+import { GwElement, css, h } from "./element.js";
+import "./gw-option-list.js";
+import type { OptionItem } from "./gw-option-list.js";
+import { base } from "./styles.js";
+
+/** Below this width the menu is a bottom sheet. */
+const sheetBelow = 600;
+
+/**
+ * A command menu on Cmd+K or Ctrl+K: a searchable list of commands in a
+ * modal near the top of the page, or a bottom sheet on phones. Picking one
+ * closes the menu and fires `pick` with its value. Esc or a click outside
+ * closes it. It won't open over another dialog, so only one overlay shows at
+ * a time. Set `shortcut="none"` to open it only with `show()`.
+ *
+ * @element gw-command-menu
+ * @summary A searchable list of commands on Cmd+K or Ctrl+K.
+ *
+ * @attr {OptionItem[]} options - The commands, as JSON.
+ * @attr {string} label - The accessible name. Defaults to `Commands`.
+ * @attr {string} placeholder - The search placeholder. Defaults to `Search commands`.
+ * @attr {string} shortcut - The key that opens it with Cmd or Ctrl, such as `mod+k`, or `none`. Defaults to `mod+k`.
+ * @attr {boolean} open - Whether it shows.
+ *
+ * @fires pick - When a command is picked, with its `value` in `detail`.
+ */
+export class GwCommandMenu extends GwElement {
+  static override properties = {
+    options: { type: "json" },
+    label: {},
+    placeholder: {},
+    shortcut: {},
+    open: { type: "boolean", reflect: true },
+  } as const;
+
+  static override styles = [
+    base,
+    css`
+      dialog {
+        top: 12vh;
+        width: min(36rem, calc(100vw - 2 * var(--gw-space-3)));
+        max-height: 70vh;
+        padding: 0;
+        margin-block: 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-panel);
+        box-shadow: var(--gw-shadow-l);
+        --gw-option-list-height: min(24rem, 56vh);
+      }
+
+      dialog::backdrop {
+        background: rgb(0 0 0 / 50%);
+      }
+
+      dialog,
+      dialog::backdrop {
+        opacity: 0;
+        transition:
+          opacity var(--gw-motion-normal) var(--gw-motion-easing),
+          scale var(--gw-motion-normal) 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;
+      }
+
+      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;
+        }
+      }
+
+      dialog[data-placement="sheet"] {
+        inset: auto 0 0;
+        width: 100%;
+        max-width: none;
+        padding-block-end: env(safe-area-inset-bottom);
+        border-end-start-radius: 0;
+        border-end-end-radius: 0;
+        scale: 1;
+        translate: 0 100%;
+        --gw-option-list-height: 60vh;
+      }
+
+      dialog[data-placement="sheet"][open] {
+        opacity: 1;
+        translate: 0 0;
+      }
+
+      @starting-style {
+        dialog[data-placement="sheet"][open] {
+          translate: 0 100%;
+        }
+      }
+
+      footer {
+        display: flex;
+        gap: var(--gw-space-3);
+        padding: var(--gw-space-2) var(--gw-space-3);
+        font-size: var(--gw-font-size-xs);
+        color: var(--gw-color-text-secondary);
+        border-block-start: var(--gw-border-width) solid
+          var(--gw-color-border-quiet);
+      }
+
+      kbd {
+        padding: 0 var(--gw-space-1);
+        font: inherit;
+        border: 1px solid var(--gw-color-border-normal);
+        border-radius: var(--gw-radius-control);
+      }
+
+      dialog[data-placement="sheet"] footer {
+        display: none;
+      }
+    `,
+  ];
+
+  declare options: readonly OptionItem[];
+  declare label: string;
+  declare placeholder: string;
+  /** `mod+k` (the default) opens it on Cmd+K or Ctrl+K; `none` turns that off. */
+  declare shortcut: string;
+  declare open: boolean;
+
+  readonly #list = h("gw-option-list", { search: true });
+
+  readonly #dialog = h(
+    "dialog",
+    {},
+    this.#list,
+    h(
+      "footer",
+      { "aria-hidden": "true" },
+      h("span", {}, h("kbd", {}, "↑"), " ", h("kbd", {}, "↓"), " to move"),
+      h("span", {}, h("kbd", {}, "Enter"), " to pick"),
+      h("span", {}, h("kbd", {}, "Esc"), " to close"),
+    ),
+  );
+
+  constructor() {
+    super();
+    this.options = [];
+    this.label = "Commands";
+    this.placeholder = "Search commands";
+    this.shortcut = "mod+k";
+    this.open = false;
+  }
+
+  show() {
+    this.open = true;
+  }
+
+  close() {
+    this.open = false;
+  }
+
+  readonly #onShortcut = (event: KeyboardEvent) => {
+    if (
+      this.shortcut === "none" ||
+      event.defaultPrevented ||
+      event.key.toLowerCase() !== "k" ||
+      !(event.metaKey || event.ctrlKey) ||
+      event.altKey ||
+      event.shiftKey
+    ) {
+      return;
+    }
+
+    event.preventDefault();
+
+    if (this.open) {
+      this.close();
+
+      return;
+    }
+
+    // One overlay at a time: another open dialog keeps the page
+    if (
+      document.querySelector(
+        "dialog[open], gw-dialog[open], gw-command-menu[open]",
+      )
+    ) {
+      return;
+    }
+
+    this.show();
+  };
+
+  override connectedCallback() {
+    super.connectedCallback();
+    document.addEventListener("keydown", this.#onShortcut);
+  }
+
+  override disconnectedCallback() {
+    document.removeEventListener("keydown", this.#onShortcut);
+    super.disconnectedCallback();
+  }
+
+  protected override create(root: ShadowRoot) {
+    this.#dialog.addEventListener("close", () => {
+      this.open = false;
+    });
+    this.#dialog.addEventListener("click", (event) => {
+      if (event.target === this.#dialog) this.close();
+    });
+    this.#list.addEventListener("pick", (event) => {
+      event.stopPropagation();
+
+      const value =
+        event instanceof CustomEvent &&
+        event.detail !== null &&
+        "value" in event.detail
+          ? String(event.detail.value)
+          : "";
+
+      this.close();
+      this.dispatchEvent(
+        new CustomEvent("pick", {
+          detail: { value },
+          bubbles: true,
+          composed: true,
+        }),
+      );
+    });
+    root.append(this.#dialog);
+  }
+
+  protected override update() {
+    const list = this.#list;
+    const dialog = this.#dialog;
+
+    list.options = Array.isArray(this.options) ? this.options : [];
+    list.label = this.label;
+    list.placeholder = this.placeholder;
+    dialog.setAttribute("aria-label", this.label);
+
+    if (this.open && !dialog.open) {
+      dialog.dataset.placement =
+        window.innerWidth < sheetBelow ? "sheet" : "center";
+      dialog.showModal();
+      list.reset();
+      document.dispatchEvent(new Event("gw-dialog-open"));
+    }
+
+    if (!this.open && dialog.open) dialog.close();
+  }
+}
+
+GwCommandMenu.define("gw-command-menu");
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "gw-command-menu": GwCommandMenu;
+  }
+}