@timmo001/groundwork-ui 0.5.0 → 0.7.0

package/src/gw-card.ts

@@ -15,6 +15,12 @@ import { base } from "./styles.js";
  * 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.
  *
+ * For a link the page's HTML has to carry, such as one with a `target` or
+ * `rel`, put an `<a>` in the `heading` slot instead of `href`. A click
+ * anywhere on the card that isn't on another control follows it, the card
+ * shows the link's hover and focus, and the link stays a real one in the
+ * page, so the rest of the card's content stays plain text.
+ *
  * @element gw-card
  * @summary A surface for one group of content, or a link to more.
  *
@@ -25,9 +31,13 @@ import { base } from "./styles.js";
  * @attr {number} lines - How many skeleton lines while loading. Defaults to 3.
  *
  * @slot - The content.
+ * @slot heading - The heading, in place of `heading`. An `<a>` here makes the whole card follow it.
  * @slot actions - Buttons beside the heading.
  *
  * @csspart card - The card's surface.
+ * @csspart header - The row with the heading and actions.
+ * @csspart heading - The heading.
+ * @csspart body - The content.
  */
 export class GwCard extends GwElement {
   static override properties = {
@@ -68,10 +78,32 @@ export class GwCard extends GwElement {
         transition: border-color var(--gw-motion-fast) var(--gw-motion-easing);
       }
 
-      a.card:hover {
+      a.card:hover,
+      .card.linked:hover {
         border-color: var(--gw-color-border-accent);
       }
 
+      /* A card following a link in its heading slot */
+      .card.linked {
+        cursor: pointer;
+        transition: border-color var(--gw-motion-fast) var(--gw-motion-easing);
+      }
+
+      .card.focused {
+        outline: var(--gw-focus-width) solid var(--gw-color-focus);
+        outline-offset: var(--gw-focus-offset);
+      }
+
+      ::slotted([slot="heading"]) {
+        font: inherit;
+        color: inherit;
+      }
+
+      ::slotted(a[slot="heading"]) {
+        text-decoration: none;
+        outline: none;
+      }
+
       header {
         display: flex;
         gap: var(--gw-space-2);
@@ -105,16 +137,24 @@ export class GwCard extends GwElement {
 
   readonly #titleSkeleton = h("gw-skeleton-text");
 
+  readonly #headingSlot = h("slot", { name: "heading" });
+
   readonly #header = h(
     "header",
-    {},
-    h("h2", {}, this.#title, this.#titleSkeleton),
+    { part: "header" },
+    h(
+      "h2",
+      { part: "heading" },
+      this.#title,
+      this.#headingSlot,
+      this.#titleSkeleton,
+    ),
     h("slot", { name: "actions" }),
   );
 
   readonly #skeleton = h("gw-skeleton-lines");
 
-  readonly #body = h("div", { class: "body" }, h("slot"));
+  readonly #body = h("div", { class: "body", part: "body" }, h("slot"));
 
   #card: HTMLElement = h("section", { class: "card", part: "card" });
 
@@ -129,6 +169,57 @@ export class GwCard extends GwElement {
     this.flush = false;
     this.loading = false;
     this.lines = 3;
+
+    // A click on the card, but not on another control in it, follows the
+    // link in the heading slot
+    this.addEventListener("click", (event) => {
+      const link = this.#link();
+
+      if (link === null || this.loading) return;
+
+      const path = event.composedPath();
+      const own = path.slice(0, path.indexOf(this));
+
+      if (
+        own.some(
+          (node) =>
+            node instanceof HTMLElement &&
+            node.matches(
+              "a, button, input, select, textarea, label, [tabindex], gw-button",
+            ),
+        )
+      ) {
+        return;
+      }
+
+      // Selecting text in the card shouldn't open the link
+      if (getSelection()?.toString()) return;
+
+      link.click();
+    });
+
+    const focus = () => {
+      this.#card.classList.toggle(
+        "focused",
+        this.#link()?.matches(":focus-visible") === true,
+      );
+    };
+
+    this.addEventListener("focusin", focus);
+    this.addEventListener("focusout", focus);
+
+    this.#headingSlot.addEventListener("slotchange", () => {
+      this.requestUpdate("heading");
+    });
+  }
+
+  /** The `<a>` in the heading slot, or holding it, when there is one. */
+  #link(): HTMLAnchorElement | null {
+    const heading = this.querySelector(":scope > [slot='heading']");
+
+    if (heading instanceof HTMLAnchorElement) return heading;
+
+    return heading?.querySelector("a") ?? null;
   }
 
   protected override create(root: ShadowRoot) {
@@ -160,9 +251,14 @@ export class GwCard extends GwElement {
     if (this.#card instanceof HTMLAnchorElement) this.#card.href = this.href;
 
     setAttribute(this.#card, "aria-busy", this.loading ? "true" : null);
+
+    const slotted = this.querySelector(":scope > [slot='heading']") !== null;
+
+    this.#card.classList.toggle("linked", this.#link() !== null && !this.href);
     this.#title.textContent = this.heading;
-    this.#titleSkeleton.hidden = this.heading !== "" || !this.loading;
-    this.#header.hidden = !this.heading && !this.loading;
+    this.#titleSkeleton.hidden =
+      this.heading !== "" || slotted || !this.loading;
+    this.#header.hidden = !this.heading && !slotted && !this.loading;
     this.#skeleton.lines = this.lines;
     this.#skeleton.hidden = !this.loading;
     this.#body.hidden = this.loading;

package/src/gw-chip.ts

@@ -7,7 +7,13 @@
 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";
+import {
+  base,
+  controlSizes,
+  createIcon,
+  setIconPath,
+  type Tone,
+} from "./styles.js";
 
 /**
  * A short status or category, tinted by its `tone`. While `loading`, a
@@ -19,42 +25,56 @@ import { base, createIcon, setIconPath, type Tone } from "./styles.js";
  * @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.
+ * @attr {"xs"|"small"|"medium"|"large"|"xl"} size - The size, around 32px tall at medium. Defaults to `medium`.
  *
  * @slot - The text.
  * @slot icon - An icon before the text, in place of `icon`.
  *
  * @csspart chip - The chip.
+ *
+ * @cssprop --gw-tone-fill - The tint, for a tone of your own. `tone` sets it.
+ * @cssprop --gw-tone-border - The border. `tone` sets it.
+ * @cssprop --gw-chip-scale - Scales the chip, around 1 for medium.
+ * @cssprop --gw-control-scale - Scales its height and icon with the theme's density. The theme sets it.
  */
 export class GwChip extends GwElement {
   static override properties = {
     tone: { reflect: true },
     icon: {},
     loading: { type: "boolean", reflect: true },
+    size: { reflect: true },
   } as const;
 
   static override styles = [
     base,
+    controlSizes("chip"),
     css`
       :host {
         display: inline-flex;
       }
 
-      /* 32px, with 12px padding */
+      /* 32px at medium, with 12px padding */
       .chip {
+        --gw-size: var(--gw-chip-scale, 1);
+        --gw-scale: calc(var(--gw-size) * var(--gw-control-scale, 1));
+        --gw-icon-size: calc(1rem * var(--gw-scale));
+
         display: inline-flex;
-        gap: var(--gw-space-2);
+        gap: calc(var(--gw-space-2) * var(--gw-size));
         align-items: center;
         box-sizing: border-box;
-        height: 2rem;
-        padding: 0 var(--gw-space-3);
-        font-size: var(--gw-font-size-xs);
+        height: calc(2rem * var(--gw-scale));
+        padding: 0 calc(var(--gw-space-3) * var(--gw-size));
+        font-size: max(
+          var(--gw-font-size-2xs),
+          calc(var(--gw-font-size-xs) * var(--gw-size))
+        );
         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 {
@@ -69,6 +89,7 @@ export class GwChip extends GwElement {
   /** SVG path data for an icon before the text, instead of the `icon` slot. */
   declare icon: string;
   declare loading: boolean;
+  declare size: "xs" | "small" | "medium" | "large" | "xl";
 
   readonly #icon = createIcon("");
 
@@ -90,6 +111,7 @@ export class GwChip extends GwElement {
     this.tone = "neutral";
     this.icon = "";
     this.loading = false;
+    this.size = "medium";
   }
 
   protected override create(root: ShadowRoot) {

package/src/gw-command-menu.ts

@@ -28,6 +28,10 @@ const sheetBelow = 600;
  * @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.
  *
+ * @csspart dialog - The menu's surface.
+ * @csspart list - The `gw-option-list` of commands.
+ * @csspart footer - The row of key hints.
+ *
  * @fires {CustomEvent<{ value: string }>} pick - When a command is picked, with its `value` in `detail`.
  */
 export class GwCommandMenu extends GwElement {
@@ -150,15 +154,15 @@ export class GwCommandMenu extends GwElement {
   declare shortcut: string;
   declare open: boolean;
 
-  readonly #list = h("gw-option-list", { search: true });
+  readonly #list = h("gw-option-list", { search: true, part: "list" });
 
   readonly #dialog = h(
     "dialog",
-    {},
+    { part: "dialog" },
     this.#list,
     h(
       "footer",
-      { "aria-hidden": "true" },
+      { part: "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"),

package/src/gw-dialog.ts

@@ -28,6 +28,12 @@ const closeIcon =
  * @slot - The content.
  * @slot actions - Buttons; one with a `value` closes it with that value.
  *
+ * @csspart dialog - The dialog's surface.
+ * @csspart header - The row with the heading and close button.
+ * @csspart heading - The heading.
+ * @csspart body - The content.
+ * @csspart footer - The actions row.
+ *
  * @fires {Event} close - When it closes; `returnValue` holds the button's value.
  */
 export class GwDialog extends GwElement {
@@ -139,9 +145,13 @@ export class GwDialog extends GwElement {
     this.open = false;
   }
 
-  readonly #heading = h("h2", { id: "heading" });
+  readonly #heading = h("h2", { id: "heading", part: "heading" });
 
-  readonly #footer = h("footer", {}, h("slot", { name: "actions" }));
+  readonly #footer = h(
+    "footer",
+    { part: "footer" },
+    h("slot", { name: "actions" }),
+  );
 
   readonly #closeButton = h(
     "gw-button",
@@ -158,9 +168,9 @@ export class GwDialog extends GwElement {
 
   readonly #dialog = h(
     "dialog",
-    { "aria-labelledby": "heading" },
-    h("header", {}, this.#heading, this.#closeButton),
-    h("div", { class: "body" }, h("slot")),
+    { "aria-labelledby": "heading", part: "dialog" },
+    h("header", { part: "header" }, this.#heading, this.#closeButton),
+    h("div", { class: "body", part: "body" }, h("slot")),
     this.#footer,
   );
 

package/src/gw-dot.ts

@@ -17,6 +17,8 @@ import { base, type Tone } from "./styles.js";
  * @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.
+ *
+ * @cssprop --gw-tone - The color, for a tone of your own. `tone` sets it.
  */
 export class GwDot extends GwElement {
   static override properties = {

package/src/gw-expansion.ts

@@ -25,6 +25,8 @@ import { base } from "./styles.js";
  *
  * @csspart details - The native `<details>`.
  * @csspart summary - The summary row.
+ * @csspart heading - The heading.
+ * @csspart description - The line under the heading.
  * @csspart content - The content's wrapper.
  *
  * @fires {Event} toggle - When it opens or closes.
@@ -169,9 +171,12 @@ export class GwExpansion extends GwElement {
   declare description: string;
   declare open: boolean;
 
-  readonly #heading = h("span", { class: "heading" });
+  readonly #heading = h("span", { class: "heading", part: "heading" });
 
-  readonly #description = h("span", { class: "description" });
+  readonly #description = h("span", {
+    class: "description",
+    part: "description",
+  });
 
   readonly #details = h(
     "details",

package/src/gw-facts.ts

@@ -28,6 +28,10 @@ const skeletonWidths = ["60%", "40%", "75%", "50%", "65%"];
  * @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.
+ *
+ * @csspart list - The description list.
+ * @csspart label - Each label.
+ * @csspart value - Each value.
  */
 export class GwFacts extends GwElement {
   static override properties = {
@@ -69,7 +73,7 @@ export class GwFacts extends GwElement {
   declare loading: boolean;
   declare rows: number;
 
-  readonly #list = h("dl");
+  readonly #list = h("dl", { part: "list" });
 
   #rendered = false;
 
@@ -97,13 +101,13 @@ export class GwFacts extends GwElement {
         ...Array.from({ length: count }, (_, index) => [
           h(
             "dt",
-            {},
+            { part: "label" },
             items[index]?.label ??
               h("gw-skeleton-text", { style: "--gw-skeleton-width: 5rem" }),
           ),
           h(
             "dd",
-            {},
+            { part: "value" },
             h("gw-skeleton-text", {
               style: `--gw-skeleton-width: ${skeletonWidths[index % skeletonWidths.length]}`,
             }),
@@ -114,8 +118,12 @@ export class GwFacts extends GwElement {
       this.#list.removeAttribute("aria-busy");
       this.#list.replaceChildren(
         ...items.flatMap((item) => [
-          h("dt", {}, item.label),
-          h("dd", {}, loaded ? h("span", {}, item.value) : item.value),
+          h("dt", { part: "label" }, item.label),
+          h(
+            "dd",
+            { part: "value" },
+            loaded ? h("span", {}, item.value) : item.value,
+          ),
         ]),
       );
     }

package/src/gw-gauge.ts

@@ -76,6 +76,12 @@ const circle = (className: string) => {
  * @attr {boolean} inverted - Lower is worse, such as for a battery.
  * @attr {boolean} loading - Pulses the track and shows a skeleton for the reading.
  *
+ * @csspart dial - The dial, with the arc and the reading.
+ * @csspart value - The reading's number.
+ * @csspart unit - The unit after it.
+ * @csspart label - What it measures.
+ * @csspart caption - The line under the label.
+ *
  * @cssprop --gw-gauge-size - The dial's width. Defaults to `8.5rem`.
  * @cssprop --gw-gauge-color - The arc's color, overriding the thresholds.
  */
@@ -208,11 +214,11 @@ export class GwGauge extends GwElement {
 
   readonly #fill = circle("fill");
 
-  readonly #dial = h("div", { class: "dial", role: "meter" });
+  readonly #dial = h("div", { class: "dial", part: "dial", role: "meter" });
 
-  readonly #value = h("span", { class: "value" });
+  readonly #value = h("span", { class: "value", part: "value" });
 
-  readonly #unit = h("span", { class: "unit" });
+  readonly #unit = h("span", { class: "unit", part: "unit" });
 
   readonly #shown = h("span", { class: "shown" }, this.#value, this.#unit);
 
@@ -220,9 +226,9 @@ export class GwGauge extends GwElement {
     style: "--gw-skeleton-width: 2em",
   });
 
-  readonly #label = h("span", { class: "label" });
+  readonly #label = h("span", { class: "label", part: "label" });
 
-  readonly #caption = h("span", { class: "caption" });
+  readonly #caption = h("span", { class: "caption", part: "caption" });
 
   readonly #captionSkeleton = h("gw-skeleton-text", {
     style: "--gw-skeleton-width: 5rem",

package/src/gw-input.ts

@@ -25,6 +25,10 @@ import { LightElement, fieldId } from "./fields.js";
  * @attr {string} error - An error under the field, which marks it invalid.
  * @attr {boolean} required - Requires a value.
  * @attr {boolean} disabled - Disables the field.
+ * @attr {"xs"|"small"|"medium"|"large"|"xl"} size - The field's size, 40px tall at medium. Defaults to `medium`.
+ *
+ * @cssprop --gw-field-scale - Scales the field, around 1 for medium.
+ * @cssprop --gw-control-scale - Scales its height with the theme's density. The theme sets it.
  */
 export class GwInput extends LightElement {
   static override properties = {
@@ -39,6 +43,7 @@ export class GwInput extends LightElement {
     error: {},
     required: { type: "boolean" },
     disabled: { type: "boolean" },
+    size: { reflect: true },
   } as const;
 
   declare label: string;
@@ -53,6 +58,7 @@ export class GwInput extends LightElement {
   declare error: string;
   declare required: boolean;
   declare disabled: boolean;
+  declare size: "xs" | "small" | "medium" | "large" | "xl";
 
   readonly #id = fieldId();
 
@@ -79,6 +85,7 @@ export class GwInput extends LightElement {
     this.error = "";
     this.required = false;
     this.disabled = false;
+    this.size = "medium";
   }
 
   protected override create(root: HTMLElement) {

package/src/gw-menu-button.ts

@@ -5,7 +5,7 @@
  * @module
  */
 import { GwElement, css, h } from "./element.js";
-import { base, createIcon, setIconPath } from "./styles.js";
+import { base, controlSizes, createIcon, setIconPath } from "./styles.js";
 
 export interface MenuItem {
   readonly value: string;
@@ -38,9 +38,13 @@ export interface MenuItem {
  * @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.
+ * @attr {"xs"|"small"|"medium"|"large"|"xl"} size - The trigger's size, 24 to 56px tall. Defaults to `medium`.
  *
  * @csspart trigger - The button that opens the menu.
  *
+ * @cssprop --gw-menu-button-scale - Scales the trigger, around 1 for medium.
+ * @cssprop --gw-control-scale - Scales its height and icon with the theme's density. The theme sets it.
+ *
  * @fires {CustomEvent<{ value: string }>} select - When an item or action is chosen, with its `value` in `detail`.
  */
 export class GwMenuButton extends GwElement {
@@ -50,10 +54,12 @@ export class GwMenuButton extends GwElement {
     empty: {},
     items: { type: "json" },
     actions: { type: "json" },
+    size: { reflect: true },
   } as const;
 
   static override styles = [
     base,
+    controlSizes("menu-button"),
     css`
       :host {
         position: relative;
@@ -62,14 +68,18 @@ export class GwMenuButton extends GwElement {
       }
 
       .trigger {
+        --gw-size: var(--gw-menu-button-scale, 1);
+        --gw-scale: calc(var(--gw-size) * var(--gw-control-scale, 1));
+        --gw-icon-size: calc(1.25rem * var(--gw-scale));
+
         display: inline-flex;
-        gap: var(--gw-space-2);
+        gap: calc(var(--gw-space-2) * var(--gw-size));
         align-items: center;
         box-sizing: border-box;
-        height: 2.5rem;
-        padding: 0 var(--gw-space-4);
+        height: calc(2.5rem * var(--gw-scale));
+        padding: 0 calc(var(--gw-space-4) * var(--gw-size));
         font: inherit;
-        font-size: var(--gw-font-size-s);
+        font-size: calc(var(--gw-font-size-s) * var(--gw-size));
         font-weight: var(--gw-font-weight-strong);
         color: var(--gw-color-text-strong);
         cursor: pointer;
@@ -233,6 +243,7 @@ export class GwMenuButton extends GwElement {
   declare empty: string;
   declare items: readonly MenuItem[];
   declare actions: readonly MenuItem[];
+  declare size: "xs" | "small" | "medium" | "large" | "xl";
 
   readonly #trigger = h("button", {
     class: "trigger",
@@ -264,6 +275,7 @@ export class GwMenuButton extends GwElement {
     this.empty = "Nothing here yet";
     this.items = [];
     this.actions = [];
+    this.size = "medium";
   }
 
   /** The enabled items then actions, in the order arrow keys move through them. */

package/src/gw-meter.ts

@@ -26,6 +26,11 @@ import { base, type Tone } from "./styles.js";
  * @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.
+ *
+ * @csspart top - The row with the label and value.
+ * @csspart value - The value as shown.
+ * @csspart track - The bar's track.
+ * @csspart fill - The filled part of the bar.
  */
 export class GwMeter extends GwElement {
   static override properties = {
@@ -93,7 +98,7 @@ export class GwMeter extends GwElement {
   declare tone: Tone | undefined;
   declare loading: boolean;
 
-  readonly #top = h("div", { class: "top" });
+  readonly #top = h("div", { class: "top", part: "top" });
 
   readonly #label = h("span");
 
@@ -101,15 +106,23 @@ export class GwMeter extends GwElement {
     style: "--gw-skeleton-width: 6rem",
   });
 
-  readonly #value = h("span", { class: "value", "aria-hidden": "true" });
+  readonly #value = h("span", {
+    class: "value",
+    part: "value",
+    "aria-hidden": "true",
+  });
 
   readonly #valueSkeleton = h("gw-skeleton-text", {
     style: "--gw-skeleton-width: 2.5rem",
   });
 
-  readonly #fill = h("div", { class: "fill" });
+  readonly #fill = h("div", { class: "fill", part: "fill" });
 
-  readonly #track = h("div", { class: "track", role: "meter" }, this.#fill);
+  readonly #track = h(
+    "div",
+    { class: "track", part: "track", role: "meter" },
+    this.#fill,
+  );
 
   readonly #bar = h("gw-skeleton", { class: "bar" });
 

package/src/gw-notification-center.ts

@@ -29,6 +29,10 @@ const emptyIcon =
  *
  * @slot - The `gw-notification` cards.
  *
+ * @csspart header - The row with the heading and Clear all.
+ * @csspart heading - The heading.
+ * @csspart list - The list of cards.
+ *
  * @fires {Event} clear - When Clear all is pressed.
  */
 export class GwNotificationCenter extends GwElement {
@@ -75,7 +79,7 @@ export class GwNotificationCenter extends GwElement {
 
   declare heading: string;
 
-  readonly #heading = h("h2");
+  readonly #heading = h("h2", { part: "heading" });
 
   readonly #clear = h(
     "gw-button",
@@ -83,7 +87,11 @@ export class GwNotificationCenter extends GwElement {
     "Clear all",
   );
 
-  readonly #list = h("div", { class: "list", role: "list" }, h("slot"));
+  readonly #list = h(
+    "div",
+    { class: "list", part: "list", role: "list" },
+    h("slot"),
+  );
 
   readonly #empty = h(
     "gw-empty-state",
@@ -138,7 +146,10 @@ export class GwNotificationCenter extends GwElement {
     this.#clear.addEventListener("click", () => {
       this.clear();
     });
-    root.append(h("header", {}, this.#heading, this.#clear), this.#body);
+    root.append(
+      h("header", { part: "header" }, this.#heading, this.#clear),
+      this.#body,
+    );
   }
 
   protected override update() {

package/src/gw-notification.ts

@@ -34,6 +34,8 @@ const closeIcon =
  *
  * @csspart card - The card.
  *
+ * @cssprop --gw-tone - The icon's color, for a tone of your own. `tone` sets it.
+ *
  * @fires {Event} dismiss - When the close button is pressed. Cancel it to keep the card.
  */
 export class GwNotification extends GwElement {