@timmo001/groundwork-ui 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timmo001/groundwork-ui",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Groundwork's framework-free web components, styled by the --gw-* tokens",
   "license": "Apache-2.0",
   "type": "module",
@@ -10,9 +10,11 @@
   },
   "files": [
     "src",
+    "custom-elements.json",
     "README.md",
     "LICENSE"
   ],
+  "customElements": ".manifest-check/custom-elements.json",
   "sideEffects": true,
   "publishConfig": {
     "access": "public",
@@ -28,9 +30,12 @@
     "lint": "oxlint .",
     "typecheck": "tsc",
     "format": "prettier --write .",
-    "format:check": "prettier --check ."
+    "format:check": "prettier --check .",
+    "gen": "bun run scripts/manifest.ts",
+    "gen:check": "bun run scripts/manifest.ts --check"
   },
   "devDependencies": {
+    "@custom-elements-manifest/analyzer": "0.11.0",
     "@oxlint/plugins": "1.90.0",
     "@timmo001/oxlint-rules": "0.6.3",
     "oxlint": "1.90.0",

package/src/events.ts

@@ -0,0 +1,44 @@
+// Generated by `mise run gen` from the elements' `@fires` docstrings. Don't edit.
+
+/** The events each `gw-` element fires, by tag. `on()` reads it. */
+export interface GwEventMap {
+  "gw-app-bar": {
+    toggle: Event;
+  };
+  "gw-command-menu": {
+    pick: CustomEvent<{ value: string }>;
+  };
+  "gw-dialog": {
+    close: Event;
+  };
+  "gw-expansion": {
+    toggle: Event;
+  };
+  "gw-menu-button": {
+    select: CustomEvent<{ value: string }>;
+  };
+  "gw-notification": {
+    dismiss: Event;
+  };
+  "gw-notification-center": {
+    clear: Event;
+  };
+  "gw-option-list": {
+    pick: CustomEvent<{ value: string }>;
+  };
+  "gw-popover": {
+    close: Event;
+  };
+  "gw-segmented": {
+    change: Event;
+  };
+  "gw-select": {
+    change: Event;
+  };
+  "gw-theme-picker": {
+    reset: Event;
+    mode: CustomEvent<{ mode: string }>;
+    theme: CustomEvent<{ id: string }>;
+    import: CustomEvent<{ text: string, name: string }>;
+  };
+}

package/src/fields.ts

@@ -216,6 +216,40 @@ export const fieldStyles = css`
     background: rgb(0 0 0 / 40%);
   }
 
+  /* With multiple, a full-width Clear under the list empties the choice */
+  gw-select .gw-select-clear {
+    display: block;
+    width: 100%;
+    min-height: 2.5rem;
+    padding: 0 var(--gw-space-3);
+    font: inherit;
+    font-size: var(--gw-font-size-s);
+    font-weight: var(--gw-font-weight-strong);
+    color: var(--gw-color-text-secondary);
+    cursor: pointer;
+    background: none;
+    border: 0;
+    border-block-start: var(--gw-border-width) solid
+      var(--gw-color-border-quiet);
+    transition:
+      color var(--gw-motion-fast) var(--gw-motion-easing),
+      background-color var(--gw-motion-fast) var(--gw-motion-easing);
+  }
+
+  gw-select .gw-select-clear:hover {
+    color: var(--gw-color-text-strong);
+    background: var(--gw-color-fill-neutral-hovered);
+  }
+
+  gw-select .gw-select-clear:focus-visible {
+    outline: var(--gw-focus-width) solid var(--gw-color-focus);
+    outline-offset: calc(var(--gw-focus-width) * -1);
+  }
+
+  gw-select .gw-select-clear[hidden] {
+    display: none;
+  }
+
   :where(gw-input, gw-select) :where(input, .gw-select-trigger):hover {
     border-color: var(--gw-color-border-loud);
   }

package/src/gw-app-bar.ts

@@ -0,0 +1,343 @@
+/**
+ * `gw-app-bar`: a header pinned to the top, floating once the page scrolls.
+ * Docs: https://groundwork.timmo.dev/components/layout/#app-bar
+ *
+ * @module
+ */
+import { GwElement, css, h, setAttribute } from "./element.js";
+import { base, createIcon, setIconPath } from "./styles.js";
+
+// MDI's menu and close
+const menuIcon = "M3,6H21V8H3V6M3,11H21V13H3V11M3,16H21V18H3V16Z";
+
+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";
+
+/** Below this width the nav moves into a menu. */
+const menuBelow = 600;
+
+/**
+ * A site or app header pinned to the top of the page, with a brand, nav
+ * links and actions, full width with its content kept to the content width.
+ * It's transparent at first, then gets a blurred surface and a bottom border
+ * once the page scrolls, or once the element
+ * `reveal-after` names scrolls out of view, such as a hero. With
+ * `reveal-after` the brand stays hidden until then, so a large logo in the
+ * hero hands over to the small one in the bar.
+ *
+ * `overlay` lays it over the top of the page rather than taking room, for a
+ * page that opens with a hero. Below 600px wide the nav moves into a menu
+ * opened from a button, which closes on Esc, a click outside or a link.
+ *
+ * @element gw-app-bar
+ * @summary A header pinned to the top, floating once the page scrolls.
+ *
+ * @attr {string} reveal-after - A CSS selector for the element, such as a hero, to scroll past before the bar floats and the brand shows.
+ * @attr {boolean} overlay - Lays the bar over the top of the page instead of taking room.
+ * @attr {boolean} floating - Whether it floats. Set by the bar as the page scrolls.
+ * @attr {boolean} menu-open - Whether the nav menu is open on narrow screens.
+ * @attr {string} menu-label - The menu button's accessible name. Defaults to `Menu`.
+ *
+ * @slot brand - A logo or name linking home.
+ * @slot - The nav links.
+ * @slot actions - Icon links and buttons at the end.
+ *
+ * @csspart bar - The bar.
+ * @csspart nav - The nav links' container, the menu panel on narrow screens.
+ *
+ * @fires {Event} toggle - When the nav menu opens or closes.
+ */
+export class GwAppBar extends GwElement {
+  static override properties = {
+    revealAfter: { attribute: "reveal-after" },
+    overlay: { type: "boolean", reflect: true },
+    floating: { type: "boolean", reflect: true },
+    menuOpen: { type: "boolean", attribute: "menu-open", reflect: true },
+    menuLabel: { attribute: "menu-label" },
+  } as const;
+
+  static override styles = [
+    base,
+    css`
+      :host {
+        position: sticky;
+        inset-block-start: 0;
+        z-index: 50;
+        display: block;
+      }
+
+      :host([overlay]) {
+        position: fixed;
+        inset-inline: 0;
+      }
+
+      .bar {
+        position: relative;
+        display: flex;
+        gap: var(--gw-space-3);
+        align-items: center;
+        min-height: 3.5rem;
+        padding: var(--gw-space-1)
+          max(var(--gw-space-3), (100% - var(--gw-content-width)) / 2);
+        border-block-end: max(var(--gw-border-width), 1px) solid transparent;
+        transition:
+          background-color var(--gw-motion-normal) var(--gw-motion-easing),
+          border-color var(--gw-motion-normal) var(--gw-motion-easing),
+          backdrop-filter var(--gw-motion-normal) var(--gw-motion-easing);
+      }
+
+      :host([floating]) .bar,
+      :host([menu-open]) .bar {
+        background: color-mix(
+          in oklab,
+          var(--gw-color-surface-default) 82%,
+          transparent
+        );
+        border-color: var(--gw-color-border-quiet);
+        backdrop-filter: blur(12px) saturate(1.4);
+      }
+
+      .brand {
+        display: flex;
+        flex: none;
+        align-items: center;
+        transition:
+          opacity var(--gw-motion-normal) var(--gw-motion-easing),
+          translate var(--gw-motion-normal) var(--gw-motion-easing);
+      }
+
+      :host([reveal-after]:not([floating])) .brand {
+        pointer-events: none;
+        visibility: hidden;
+        opacity: 0;
+        translate: 0 -0.25rem;
+        transition:
+          opacity var(--gw-motion-normal) var(--gw-motion-easing),
+          translate var(--gw-motion-normal) var(--gw-motion-easing),
+          visibility var(--gw-motion-normal) allow-discrete;
+      }
+
+      .nav {
+        display: flex;
+        flex: 1;
+        gap: var(--gw-space-1);
+        align-items: center;
+        min-width: 0;
+      }
+
+      .actions {
+        display: flex;
+        flex: none;
+        gap: var(--gw-space-1);
+        align-items: center;
+        margin-inline-start: auto;
+      }
+
+      .menu {
+        display: none;
+        place-items: center;
+        width: 2.5rem;
+        height: 2.5rem;
+        padding: 0;
+        color: var(--gw-color-text-strong);
+        cursor: pointer;
+        background: none;
+        border: 0;
+        border-radius: var(--gw-radius-pill);
+        transition: background-color var(--gw-motion-fast)
+          var(--gw-motion-easing);
+      }
+
+      .menu:hover {
+        background: var(--gw-color-fill-neutral-hovered);
+      }
+
+      @media (max-width: ${menuBelow - 0.02}px) {
+        .menu {
+          display: inline-grid;
+        }
+
+        .nav {
+          position: absolute;
+          inset-block-start: 100%;
+          inset-inline: 0;
+          flex-direction: column;
+          gap: var(--gw-space-0-5);
+          align-items: stretch;
+          padding: var(--gw-space-2) var(--gw-space-3);
+          visibility: hidden;
+          background: var(--gw-color-surface-default);
+          border-block-end: max(var(--gw-border-width), 1px) solid
+            var(--gw-color-border-quiet);
+          box-shadow: var(--gw-shadow-m);
+          opacity: 0;
+          translate: 0 -0.5rem;
+          transition:
+            opacity var(--gw-motion-fast) var(--gw-motion-easing),
+            translate var(--gw-motion-normal) var(--gw-motion-easing),
+            visibility var(--gw-motion-normal) allow-discrete;
+        }
+
+        :host([menu-open]) .nav {
+          visibility: visible;
+          opacity: 1;
+          translate: 0 0;
+        }
+      }
+    `,
+  ];
+
+  declare revealAfter: string;
+  declare overlay: boolean;
+  declare floating: boolean;
+  declare menuOpen: boolean;
+  declare menuLabel: string;
+
+  readonly #menuIcon = createIcon(menuIcon);
+
+  readonly #menu = h(
+    "button",
+    { type: "button", class: "menu", "aria-expanded": "false" },
+    this.#menuIcon,
+  );
+
+  readonly #nav = h("div", { class: "nav", part: "nav" }, h("slot"));
+
+  #observer: IntersectionObserver | undefined;
+
+  #frame = 0;
+
+  constructor() {
+    super();
+    this.revealAfter = "";
+    this.overlay = false;
+    this.floating = false;
+    this.menuOpen = false;
+    this.menuLabel = "Menu";
+  }
+
+  override connectedCallback() {
+    super.connectedCallback();
+    document.addEventListener("keydown", this.#onKeydown);
+    document.addEventListener("pointerdown", this.#onOutside, true);
+
+    if (document.readyState === "loading") {
+      document.addEventListener("DOMContentLoaded", () => this.#watch(), {
+        once: true,
+      });
+    } else {
+      this.#watch();
+    }
+  }
+
+  override disconnectedCallback() {
+    this.#unwatch();
+    document.removeEventListener("keydown", this.#onKeydown);
+    document.removeEventListener("pointerdown", this.#onOutside, true);
+    super.disconnectedCallback();
+  }
+
+  /** Opens or closes the nav menu on narrow screens. */
+  toggleMenu(open = !this.menuOpen) {
+    if (open === this.menuOpen) return;
+
+    this.menuOpen = open;
+    this.dispatchEvent(new Event("toggle"));
+  }
+
+  readonly #onScroll = () => {
+    if (this.#frame !== 0) return;
+
+    this.#frame = requestAnimationFrame(() => {
+      this.#frame = 0;
+      this.floating = window.scrollY > 0;
+    });
+  };
+
+  readonly #onKeydown = (event: KeyboardEvent) => {
+    if (event.key === "Escape" && this.menuOpen) {
+      this.toggleMenu(false);
+      this.#menu.focus();
+    }
+  };
+
+  readonly #onOutside = (event: PointerEvent) => {
+    if (this.menuOpen && !event.composedPath().includes(this)) {
+      this.toggleMenu(false);
+    }
+  };
+
+  #unwatch() {
+    this.#observer?.disconnect();
+    this.#observer = undefined;
+    window.removeEventListener("scroll", this.#onScroll);
+    cancelAnimationFrame(this.#frame);
+    this.#frame = 0;
+  }
+
+  /** Floats past the `reveal-after` element, or once the page scrolls without one. */
+  #watch() {
+    this.#unwatch();
+
+    const target = this.revealAfter
+      ? document.querySelector(this.revealAfter)
+      : null;
+
+    if (target === null) {
+      window.addEventListener("scroll", this.#onScroll, { passive: true });
+      this.floating = window.scrollY > 0;
+
+      return;
+    }
+
+    // The bar floats once the target's bottom passes under the bar
+    this.#observer = new IntersectionObserver(
+      ([entry]) => {
+        if (entry !== undefined) this.floating = !entry.isIntersecting;
+      },
+      { rootMargin: `-${this.offsetHeight}px 0px 0px 0px` },
+    );
+    this.#observer.observe(target);
+  }
+
+  protected override create(root: ShadowRoot) {
+    this.#menu.addEventListener("click", () => {
+      this.toggleMenu();
+    });
+    // A link picked from the menu closes it
+    this.#nav.addEventListener("click", (event) => {
+      if (
+        event.composedPath().some((node) => node instanceof HTMLAnchorElement)
+      ) {
+        this.toggleMenu(false);
+      }
+    });
+
+    root.append(
+      h(
+        "div",
+        { class: "bar", part: "bar" },
+        h("div", { class: "brand" }, h("slot", { name: "brand" })),
+        this.#menu,
+        this.#nav,
+        h("div", { class: "actions" }, h("slot", { name: "actions" })),
+      ),
+    );
+  }
+
+  protected override update(changed: ReadonlySet<string>) {
+    setAttribute(this.#menu, "aria-label", this.menuLabel);
+    setAttribute(this.#menu, "aria-expanded", this.menuOpen ? "true" : "false");
+    setIconPath(this.#menuIcon, this.menuOpen ? closeIcon : menuIcon);
+
+    if (changed.has("revealAfter") && this.isConnected) this.#watch();
+  }
+}
+
+GwAppBar.define("gw-app-bar");
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "gw-app-bar": GwAppBar;
+  }
+}

package/src/gw-command-menu.ts

@@ -28,7 +28,7 @@ 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.
  *
- * @fires pick - When a command is picked, with its `value` in `detail`.
+ * @fires {CustomEvent<{ value: string }>} pick - When a command is picked, with its `value` in `detail`.
  */
 export class GwCommandMenu extends GwElement {
   static override properties = {

package/src/gw-dialog.ts

@@ -28,7 +28,7 @@ const closeIcon =
  * @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.
+ * @fires {Event} close - When it closes; `returnValue` holds the button's value.
  */
 export class GwDialog extends GwElement {
   static override properties = {

package/src/gw-expansion.ts

@@ -27,7 +27,7 @@ import { base } from "./styles.js";
  * @csspart summary - The summary row.
  * @csspart content - The content's wrapper.
  *
- * @fires toggle - When it opens or closes.
+ * @fires {Event} toggle - When it opens or closes.
  */
 export class GwExpansion extends GwElement {
   static override properties = {

package/src/gw-menu-button.ts

@@ -41,7 +41,7 @@ export interface MenuItem {
  *
  * @csspart trigger - The button that opens the menu.
  *
- * @fires select - When an item or action is chosen, with its `value` in `detail`.
+ * @fires {CustomEvent<{ value: string }>} select - When an item or action is chosen, with its `value` in `detail`.
  */
 export class GwMenuButton extends GwElement {
   static override properties = {

package/src/gw-notification-center.ts

@@ -29,7 +29,7 @@ const emptyIcon =
  *
  * @slot - The `gw-notification` cards.
  *
- * @fires clear - When Clear all is pressed.
+ * @fires {Event} clear - When Clear all is pressed.
  */
 export class GwNotificationCenter extends GwElement {
   static override properties = {

package/src/gw-notification.ts

@@ -34,7 +34,7 @@ const closeIcon =
  *
  * @csspart card - The card.
  *
- * @fires dismiss - When the close button is pressed. Cancel it to keep the card.
+ * @fires {Event} dismiss - When the close button is pressed. Cancel it to keep the card.
  */
 export class GwNotification extends GwElement {
   static override properties = {

package/src/gw-option-list.ts

@@ -22,6 +22,8 @@ export interface OptionItem {
   readonly keywords?: readonly string[];
   /** Colors shown as small swatches, such as a theme's palette. */
   readonly swatches?: readonly string[];
+  /** One color shown as a dot before the label, such as a tag's color. */
+  readonly swatch?: string;
 }
 
 // MDI's magnify and check
@@ -65,23 +67,30 @@ let lastList = 0;
  * End and Page Up or Down, and pick with Enter or a click; it fires `pick`
  * with the option's value. Call `reset()` each time it's shown.
  *
+ * With `multiple`, every value in `values` is marked as chosen and the list
+ * is announced as multi-select; the owner toggles `values` on each `pick`.
+ *
  * @element gw-option-list
  * @summary A searchable, windowed list of options.
  *
  * @attr {OptionItem[]} options - The options, as JSON.
  * @attr {string} value - The selected option's value.
+ * @attr {boolean} multiple - Marks every value in `values` as chosen, for picking several.
+ * @attr {string[]} values - The chosen values with `multiple`, as JSON.
  * @attr {string} label - The list's accessible name.
  * @attr {boolean} search - Shows a search field above the list.
  * @attr {string} placeholder - The search placeholder. Defaults to `Search`.
  *
  * @cssprop --gw-option-list-height - The list's maximum height. Defaults to `20rem`.
  *
- * @fires pick - When an option is picked, with its `value` in `detail`.
+ * @fires {CustomEvent<{ value: string }>} pick - When an option is picked, with its `value` in `detail`.
  */
 export class GwOptionList extends GwElement {
   static override properties = {
     options: { type: "json" },
     value: {},
+    multiple: { type: "boolean" },
+    values: { type: "json" },
     label: {},
     search: { type: "boolean", reflect: true },
     placeholder: {},
@@ -211,7 +220,8 @@ export class GwOptionList extends GwElement {
         flex: none;
       }
 
-      .swatches span {
+      .swatches span,
+      .swatch {
         width: 0.875rem;
         height: 0.875rem;
         margin-inline-start: -0.25rem;
@@ -220,6 +230,13 @@ export class GwOptionList extends GwElement {
         border-radius: 50%;
       }
 
+      .swatch {
+        flex: none;
+        width: 0.625rem;
+        height: 0.625rem;
+        margin-inline: 0.125rem;
+      }
+
       .none {
         padding: var(--gw-space-4);
         font-size: var(--gw-font-size-s);
@@ -235,6 +252,8 @@ export class GwOptionList extends GwElement {
 
   declare options: readonly OptionItem[];
   declare value: string;
+  declare multiple: boolean;
+  declare values: readonly string[];
   declare label: string;
   declare search: boolean;
   declare placeholder: string;
@@ -276,11 +295,19 @@ export class GwOptionList extends GwElement {
     super();
     this.options = [];
     this.value = "";
+    this.multiple = false;
+    this.values = [];
     this.label = "";
     this.search = false;
     this.placeholder = "Search";
   }
 
+  #isChosen(option: OptionItem) {
+    return this.multiple
+      ? Array.isArray(this.values) && this.values.includes(option.value)
+      : option.value === this.value;
+  }
+
   /** The options left after the search, in order. */
   get filtered() {
     return this.#filtered;
@@ -296,7 +323,7 @@ export class GwOptionList extends GwElement {
     this.#build();
     this.#active = Math.max(
       0,
-      this.#filtered.findIndex((option) => option.value === this.value),
+      this.#filtered.findIndex((option) => this.#isChosen(option)),
     );
     (this.search ? this.#input : this.#listbox).focus({ preventScroll: true });
     this.#reveal(true);
@@ -420,8 +447,18 @@ export class GwOptionList extends GwElement {
     setAttribute(this.#input, "placeholder", this.placeholder);
     setAttribute(this.#input, "aria-label", this.label || this.placeholder);
     setAttribute(this.#listbox, "aria-label", this.label || null);
+    setAttribute(
+      this.#listbox,
+      "aria-multiselectable",
+      this.multiple ? "true" : null,
+    );
 
-    if (changed.has("options") || changed.has("value")) {
+    if (
+      changed.has("options") ||
+      changed.has("value") ||
+      changed.has("values") ||
+      changed.has("multiple")
+    ) {
       this.#build();
       this.#render();
     }
@@ -559,7 +596,7 @@ export class GwOptionList extends GwElement {
     }
 
     const { option, index } = row;
-    const selected = option.value === this.value;
+    const selected = this.#isChosen(option);
 
     const element = h(
       "div",
@@ -574,6 +611,7 @@ export class GwOptionList extends GwElement {
         "data-active": index === this.#active,
       },
       option.icon === undefined ? null : createIcon(option.icon),
+      option.swatch === undefined ? null : this.#swatch(option.swatch),
       h(
         "span",
         { class: "text" },
@@ -605,6 +643,14 @@ export class GwOptionList extends GwElement {
 
     return element;
   }
+
+  #swatch(color: string) {
+    const swatch = h("span", { class: "swatch", "aria-hidden": "true" });
+
+    swatch.style.background = color;
+
+    return swatch;
+  }
 }
 
 GwOptionList.define("gw-option-list");

package/src/gw-popover.ts

@@ -38,7 +38,7 @@ const sheetBelow = 600;
  * @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.
+ * @fires {Event} close - When it closes; `returnValue` holds the button's value.
  */
 export class GwPopover extends GwElement {
   static override properties = {

package/src/gw-segmented.ts

@@ -34,7 +34,7 @@ export interface Segment {
  *
  * @csspart indicator - The pill that slides to the chosen option.
  *
- * @fires change - When the chosen option changes.
+ * @fires {Event} change - When the chosen option changes.
  */
 export class GwSegmented extends GwElement {
   static override properties = {