@unabridged/midwest 0.22.1 → 0.23.0

package/README.md

@@ -3,7 +3,7 @@
 [![Rails Tests](https://github.com/unabridged/midwest/actions/workflows/rails-tests.yml/badge.svg?branch=main)](https://github.com/unabridged/midwest/actions/workflows/rails-tests.yml)
 [![Bridgetown Tests](https://github.com/unabridged/midwest/actions/workflows/bridgetown-tests.yml/badge.svg?branch=main)](https://github.com/unabridged/midwest/actions/workflows/bridgetown-tests.yml)
 [![Ruby](https://img.shields.io/badge/Ruby-3.3_%7C_3.4-CC342D?logo=ruby&logoColor=white)](https://github.com/unabridged/midwest/actions/workflows/ci.yml)
-[![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen)](https://github.com/unabridged/midwest/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/badge/coverage-96%25-brightgreen)](https://github.com/unabridged/midwest/actions/workflows/ci.yml)
 
 Midwest Component Library is an implementation of the Midwest Design System using [ViewComponent](https://github.com/github/view_component).
 

package/app/assets/javascript/midwest/index.ts

@@ -32,6 +32,10 @@ import PasswordRequirements from '../../../components/midwest/password_requireme
 import CodeBlock from '../../../components/midwest/code_block_component/code_block_component_controller'
 import DatePicker from '../../../components/midwest/form/date_picker_component/date_picker_component_controller'
 import TimePicker from '../../../components/midwest/form/time_picker_component/time_picker_component_controller'
+import IntersectionObserver from '../../../components/midwest/intersection_observer_component/intersection_observer_component_controller'
+import FocusTrap from '../../../components/midwest/focus_trap_component/focus_trap_component_controller'
+import Onboarding from '../../../components/midwest/onboarding_component/onboarding_component_controller'
+import ThemeSwitch from '../../../components/midwest/form/switch_component/theme_switch_controller'
 /* IMPORTS */
 
 export { Card, Banner, CountdownTimer, Chart }
@@ -71,5 +75,9 @@ export function registerMidwestControllers (application: any) {
   application.register('midwest-code-block', CodeBlock)
   application.register('midwest-date-picker', DatePicker)
   application.register('midwest-time-picker', TimePicker)
+  application.register('midwest-intersection-observer', IntersectionObserver)
+  application.register('midwest-focus-trap', FocusTrap)
+  application.register('midwest-onboarding', Onboarding)
+  application.register('midwest-theme-switch', ThemeSwitch)
   /* EXPORTS */
 }

package/app/assets/javascript/midwest/keyboard_navigation.ts

@@ -0,0 +1,68 @@
+// Shared keyboard-navigation helpers for menu/list components.
+//
+// Implements the WAI-ARIA "roving focus" pattern: arrow keys move DOM focus
+// between a flat list of items, Home/End jump to the ends, and Escape/Tab hand
+// control back to the caller (typically to close a popover and restore focus).
+// Components own *which* elements are navigable and *what* closing means; this
+// module owns the key handling so the behavior stays consistent across the
+// library.
+
+const NAVIGATION_KEYS = ['ArrowDown', 'ArrowUp', 'Home', 'End', 'Escape', 'Tab']
+
+export interface RovingFocusOptions {
+  // Called on Escape. Typically closes the menu and returns focus to the trigger.
+  onEscape?: () => void
+  // Called on Tab. The default Tab behavior is left intact so focus still leaves
+  // the menu; use this to close the menu alongside it.
+  onTab?: () => void
+  // When true (default) arrow navigation wraps from the last item to the first
+  // and vice versa. When false it stops at the ends.
+  loop?: boolean
+}
+
+// Handles a keydown against a roving-focus list. Returns true when the event
+// was one this helper is responsible for, so callers can `stopPropagation()`
+// only for keys that were actually handled.
+export function handleRovingFocusKeydown (
+  event: KeyboardEvent,
+  items: HTMLElement[],
+  options: RovingFocusOptions = {}
+): boolean {
+  if (items.length === 0) return false
+  if (!NAVIGATION_KEYS.includes(event.key)) return false
+
+  const { onEscape, onTab, loop = true } = options
+  const current = items.findIndex(item => item === document.activeElement)
+
+  switch (event.key) {
+    case 'ArrowDown': {
+      event.preventDefault()
+      const next = current < items.length - 1 ? current + 1 : (loop ? 0 : items.length - 1)
+      items[next].focus()
+      break
+    }
+    case 'ArrowUp': {
+      event.preventDefault()
+      const prev = current > 0 ? current - 1 : (loop ? items.length - 1 : 0)
+      items[prev].focus()
+      break
+    }
+    case 'Home':
+      event.preventDefault()
+      items[0].focus()
+      break
+    case 'End':
+      event.preventDefault()
+      items[items.length - 1].focus()
+      break
+    case 'Escape':
+      event.preventDefault()
+      onEscape?.()
+      break
+    case 'Tab':
+      onTab?.()
+      break
+  }
+
+  return true
+}

package/app/assets/javascript/midwest.js

@@ -2511,6 +2511,46 @@ const computePosition = (reference, floating, options) => {
   });
 };
 
+const NAVIGATION_KEYS = ["ArrowDown", "ArrowUp", "Home", "End", "Escape", "Tab"];
+function handleRovingFocusKeydown(event, items, options = {}) {
+  if (items.length === 0)
+    return false;
+  if (!NAVIGATION_KEYS.includes(event.key))
+    return false;
+  const { onEscape, onTab, loop = true } = options;
+  const current = items.findIndex((item) => item === document.activeElement);
+  switch (event.key) {
+    case "ArrowDown": {
+      event.preventDefault();
+      const next = current < items.length - 1 ? current + 1 : loop ? 0 : items.length - 1;
+      items[next].focus();
+      break;
+    }
+    case "ArrowUp": {
+      event.preventDefault();
+      const prev = current > 0 ? current - 1 : loop ? items.length - 1 : 0;
+      items[prev].focus();
+      break;
+    }
+    case "Home":
+      event.preventDefault();
+      items[0].focus();
+      break;
+    case "End":
+      event.preventDefault();
+      items[items.length - 1].focus();
+      break;
+    case "Escape":
+      event.preventDefault();
+      onEscape?.();
+      break;
+    case "Tab":
+      onTab?.();
+      break;
+  }
+  return true;
+}
+
 class Dropdown extends Controller {
   static values = {
     computed: { type: Boolean, default: false },
@@ -2564,45 +2604,15 @@ class Dropdown extends Controller {
     }
   };
   handleKeydown = (event) => {
-    const items = this.menuItems;
-    if (items.length === 0)
-      return;
-    if (!["ArrowDown", "ArrowUp", "Home", "End", "Escape", "Tab"].includes(event.key))
-      return;
-    event.stopPropagation();
-    const currentIndex = items.findIndex((item) => item === document.activeElement);
-    switch (event.key) {
-      case "ArrowDown": {
-        event.preventDefault();
-        const next = currentIndex < items.length - 1 ? currentIndex + 1 : 0;
-        items[next].focus();
-        break;
-      }
-      case "ArrowUp": {
-        event.preventDefault();
-        const prev = currentIndex > 0 ? currentIndex - 1 : items.length - 1;
-        items[prev].focus();
-        break;
-      }
-      case "Home":
-        event.preventDefault();
-        items[0].focus();
-        break;
-      case "End":
-        event.preventDefault();
-        items[items.length - 1].focus();
-        break;
-      case "Escape":
-        event.preventDefault();
+    const handled = handleRovingFocusKeydown(event, this.menuItems, {
+      onEscape: () => {
         this.element.hidePopover();
         requestAnimationFrame(() => this.buttonEl?.focus());
-        break;
-      case "Tab":
-        this.element.hidePopover();
-        break;
-      default:
-        return;
-    }
+      },
+      onTab: () => this.element.hidePopover()
+    });
+    if (handled)
+      event.stopPropagation();
   };
   get menuItems() {
     return Array.from(
@@ -6555,6 +6565,431 @@ class TimePicker extends Controller {
   }
 }
 
+class ViewportObserver extends Controller {
+  static values = {
+    threshold: { type: Number, default: 0 },
+    rootMargin: { type: String, default: "0px" },
+    once: { type: Boolean, default: false },
+    visibleClass: { type: String, default: "" }
+  };
+  observer = null;
+  connect() {
+    this.observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries)
+          this.handle(entry);
+      },
+      { threshold: this.thresholdValue, rootMargin: this.rootMarginValue }
+    );
+    this.observer.observe(this.element);
+  }
+  disconnect() {
+    this.observer?.disconnect();
+    this.observer = null;
+  }
+  handle(entry) {
+    if (entry.isIntersecting) {
+      this.element.setAttribute("data-intersecting", "true");
+      if (this.visibleClassValue)
+        this.element.classList.add(this.visibleClassValue);
+      this.dispatch("enter", { detail: { entry }, bubbles: true });
+      if (this.onceValue)
+        this.disconnect();
+    } else {
+      this.element.setAttribute("data-intersecting", "false");
+      if (this.visibleClassValue)
+        this.element.classList.remove(this.visibleClassValue);
+      this.dispatch("leave", { detail: { entry }, bubbles: true });
+    }
+  }
+}
+
+const FOCUSABLE$1 = [
+  "a[href]",
+  "button:not([disabled])",
+  "textarea:not([disabled])",
+  "input:not([disabled])",
+  "select:not([disabled])",
+  '[tabindex]:not([tabindex="-1"])'
+].join(", ");
+class FocusTrap extends Controller {
+  static values = {
+    active: { type: Boolean, default: true },
+    returnFocus: { type: Boolean, default: true },
+    initialFocus: { type: String, default: "" }
+  };
+  engaged = false;
+  previousFocus = null;
+  // Fires on connect for the initial value and on every subsequent change,
+  // so it is the single entry point for engaging/releasing the trap.
+  activeValueChanged(active) {
+    if (active)
+      this.engage();
+    else
+      this.release();
+  }
+  disconnect() {
+    this.release();
+  }
+  engage() {
+    if (this.engaged)
+      return;
+    this.engaged = true;
+    this.previousFocus = document.activeElement;
+    this.element.addEventListener("keydown", this.handleKeydown);
+    requestAnimationFrame(() => {
+      if (this.engaged)
+        this.focusInitial();
+    });
+  }
+  release() {
+    if (!this.engaged)
+      return;
+    this.engaged = false;
+    this.element.removeEventListener("keydown", this.handleKeydown);
+    if (this.returnFocusValue)
+      this.previousFocus?.focus();
+    this.previousFocus = null;
+  }
+  focusInitial() {
+    const target = this.initialFocusValue ? this.element.querySelector(this.initialFocusValue) : this.focusable()[0];
+    target?.focus();
+  }
+  focusable() {
+    return Array.from(
+      this.element.querySelectorAll(FOCUSABLE$1)
+    ).filter((el) => !el.closest("[inert]"));
+  }
+  handleKeydown = (event) => {
+    if (event.key !== "Tab")
+      return;
+    const focusable = this.focusable();
+    if (focusable.length === 0) {
+      event.preventDefault();
+      return;
+    }
+    const first = focusable[0];
+    const last = focusable[focusable.length - 1];
+    const active = document.activeElement;
+    if (event.shiftKey) {
+      if (active === first || !this.element.contains(active)) {
+        event.preventDefault();
+        last.focus();
+      }
+    } else if (active === last || !this.element.contains(active)) {
+      event.preventDefault();
+      first.focus();
+    }
+  };
+}
+
+const FOCUSABLE = [
+  "a[href]",
+  "button:not([disabled])",
+  "textarea:not([disabled])",
+  "input:not([disabled])",
+  "select:not([disabled])",
+  '[tabindex]:not([tabindex="-1"])'
+].join(", ");
+const GAP = 12;
+class Onboarding extends Controller {
+  static targets = ["step", "overlay", "card", "title", "body", "back", "next", "done", "arrow"];
+  static values = {
+    autoOpen: { type: Boolean, default: false },
+    confirm: { type: String, default: "" }
+  };
+  steps = [];
+  index = 0;
+  active = false;
+  previousFocus = null;
+  highlighted = null;
+  connect() {
+    this.steps = this.stepTargets.map((el) => ({
+      el,
+      name: el.dataset.name ?? "",
+      selector: el.dataset.selector ?? "",
+      position: el.dataset.position ?? "auto",
+      title: el.dataset.title ?? "",
+      nextText: el.dataset.nextText ?? "Next",
+      backText: el.dataset.backText ?? "Back",
+      completeText: el.dataset.completeText ?? "Done",
+      canClickTarget: el.dataset.canClickTarget === "true"
+    }));
+    window.addEventListener("midwest-onboarding:open", this.handleOpen);
+    if (this.autoOpenValue)
+      this.start();
+  }
+  disconnect() {
+    window.removeEventListener("midwest-onboarding:open", this.handleOpen);
+    this.teardown();
+  }
+  start() {
+    if (this.active || this.steps.length === 0)
+      return;
+    this.active = true;
+    this.previousFocus = document.activeElement;
+    this.overlayTarget.hidden = false;
+    this.cardTarget.hidden = false;
+    document.addEventListener("keydown", this.handleKeydown, true);
+    window.addEventListener("resize", this.reposition);
+    window.addEventListener("scroll", this.reposition, true);
+    this.dispatch("start", { bubbles: true });
+    this.render(0);
+  }
+  next() {
+    if (this.index < this.steps.length - 1)
+      this.render(this.index + 1);
+    else
+      this.complete();
+  }
+  back() {
+    if (this.index > 0)
+      this.render(this.index - 1);
+  }
+  // Jump to a step by its `name`.
+  show(name) {
+    const target = this.steps.findIndex((step) => step.name === name);
+    if (target >= 0) {
+      if (!this.active)
+        this.start();
+      this.render(target);
+    }
+  }
+  complete() {
+    if (!this.active)
+      return;
+    this.teardown();
+    this.dispatch("complete", { bubbles: true });
+  }
+  cancel() {
+    if (!this.active)
+      return;
+    if (this.confirmValue && !window.confirm(this.confirmValue))
+      return;
+    this.teardown();
+    this.dispatch("cancel", { bubbles: true });
+  }
+  render(index) {
+    this.index = index;
+    const step = this.steps[index];
+    this.clearHighlight();
+    this.titleTarget.textContent = step.title;
+    this.renderBody(step);
+    this.renderButtons(step, index);
+    const target = step.selector ? document.querySelector(step.selector) : null;
+    if (target) {
+      this.highlight(target, step.canClickTarget);
+      this.position(target, step.position);
+    } else {
+      this.center();
+    }
+    this.dispatch("show", { detail: { index, name: step.name }, bubbles: true });
+    this.focusCard();
+  }
+  renderBody(step) {
+    this.bodyTarget.replaceChildren();
+    const template = step.el.querySelector("template");
+    if (template)
+      this.bodyTarget.appendChild(template.content.cloneNode(true));
+  }
+  renderButtons(step, index) {
+    const isFirst = index === 0;
+    const isLast = index === this.steps.length - 1;
+    this.backTarget.textContent = step.backText;
+    this.backTarget.style.visibility = isFirst ? "hidden" : "";
+    this.nextTarget.textContent = step.nextText;
+    this.nextTarget.style.display = isLast ? "none" : "";
+    this.doneTarget.textContent = step.completeText;
+    this.doneTarget.style.display = isLast ? "" : "none";
+  }
+  highlight(target, canClickTarget) {
+    target.classList.add("midwest-onboarding-highlight");
+    target.classList.toggle("is-locked", !canClickTarget);
+    this.highlighted = target;
+    target.scrollIntoView({ behavior: "smooth", block: "center" });
+  }
+  clearHighlight() {
+    this.highlighted?.classList.remove("midwest-onboarding-highlight", "is-locked");
+    this.highlighted = null;
+  }
+  // Places the card against the target, choosing a side when `position` is auto.
+  position(target, position) {
+    const rect = target.getBoundingClientRect();
+    const card = this.cardTarget.getBoundingClientRect();
+    const vw = window.innerWidth;
+    const vh = window.innerHeight;
+    let placement = position;
+    if (placement === "auto") {
+      if (rect.bottom + card.height + GAP <= vh)
+        placement = "bottom";
+      else if (rect.top - card.height - GAP >= 0)
+        placement = "top";
+      else if (rect.right + card.width + GAP <= vw)
+        placement = "right";
+      else
+        placement = "left";
+    }
+    let top;
+    let left;
+    switch (placement) {
+      case "top":
+        top = rect.top - card.height - GAP;
+        left = rect.left + rect.width / 2 - card.width / 2;
+        break;
+      case "left":
+        top = rect.top + rect.height / 2 - card.height / 2;
+        left = rect.left - card.width - GAP;
+        break;
+      case "right":
+        top = rect.top + rect.height / 2 - card.height / 2;
+        left = rect.right + GAP;
+        break;
+      default:
+        top = rect.bottom + GAP;
+        left = rect.left + rect.width / 2 - card.width / 2;
+        break;
+    }
+    left = Math.max(8, Math.min(left, vw - card.width - 8));
+    top = Math.max(8, Math.min(top, vh - card.height - 8));
+    this.cardTarget.style.top = `${top}px`;
+    this.cardTarget.style.left = `${left}px`;
+    this.cardTarget.dataset.placement = placement;
+    this.positionArrow(placement, rect, top, left);
+  }
+  // Nudges the arrow so it points at the target's center, not the card's.
+  positionArrow(placement, rect, top, left) {
+    const card = this.cardTarget.getBoundingClientRect();
+    const arrow = this.arrowTarget.style;
+    if (placement === "top" || placement === "bottom") {
+      const targetCenter = rect.left + rect.width / 2;
+      const offset = Math.max(12, Math.min(targetCenter - left, card.width - 12));
+      arrow.left = `${offset}px`;
+      arrow.top = "";
+    } else {
+      const targetCenter = rect.top + rect.height / 2;
+      const offset = Math.max(12, Math.min(targetCenter - top, card.height - 12));
+      arrow.top = `${offset}px`;
+      arrow.left = "";
+    }
+  }
+  center() {
+    const card = this.cardTarget.getBoundingClientRect();
+    this.cardTarget.style.top = `${Math.max(8, window.innerHeight / 2 - card.height / 2)}px`;
+    this.cardTarget.style.left = `${Math.max(8, window.innerWidth / 2 - card.width / 2)}px`;
+    this.cardTarget.dataset.placement = "center";
+  }
+  focusCard() {
+    requestAnimationFrame(() => {
+      if (this.active)
+        this.cardTarget.focus();
+    });
+  }
+  teardown() {
+    this.active = false;
+    this.clearHighlight();
+    this.overlayTarget.hidden = true;
+    this.cardTarget.hidden = true;
+    document.removeEventListener("keydown", this.handleKeydown, true);
+    window.removeEventListener("resize", this.reposition);
+    window.removeEventListener("scroll", this.reposition, true);
+    this.previousFocus?.focus();
+    this.previousFocus = null;
+  }
+  handleOpen = (event) => {
+    const detail = event.detail ?? {};
+    const id = String(detail.id ?? "").replace("#", "");
+    if (id === this.element.id)
+      this.start();
+  };
+  reposition = () => {
+    if (!this.active)
+      return;
+    const step = this.steps[this.index];
+    const target = step.selector ? document.querySelector(step.selector) : null;
+    if (target)
+      this.position(target, step.position);
+    else
+      this.center();
+  };
+  handleKeydown = (event) => {
+    if (!this.active)
+      return;
+    switch (event.key) {
+      case "Escape":
+        event.preventDefault();
+        this.cancel();
+        break;
+      case "ArrowRight":
+        event.preventDefault();
+        this.next();
+        break;
+      case "ArrowLeft":
+        event.preventDefault();
+        this.back();
+        break;
+      case "Tab":
+        this.trapTab(event);
+        break;
+    }
+  };
+  // Keep Tab focus within the card while the tour is active.
+  trapTab(event) {
+    const focusable = Array.from(this.cardTarget.querySelectorAll(FOCUSABLE)).filter((el) => !el.hidden && el.offsetParent !== null && getComputedStyle(el).visibility !== "hidden");
+    if (focusable.length === 0)
+      return;
+    const first = focusable[0];
+    const last = focusable[focusable.length - 1];
+    const active = document.activeElement;
+    if (event.shiftKey) {
+      if (active === first || active === this.cardTarget || !this.cardTarget.contains(active)) {
+        event.preventDefault();
+        last.focus();
+      }
+    } else if (active === last || !this.cardTarget.contains(active)) {
+      event.preventDefault();
+      first.focus();
+    }
+  }
+}
+
+class ThemeSwitch extends Controller {
+  static values = {
+    storageKey: { type: String, default: "midwest-theme" }
+  };
+  connect() {
+    const isDark = this.resolveTheme() === "dark";
+    this.apply(isDark);
+    this.element.checked = isDark;
+  }
+  toggle() {
+    const isDark = this.element.checked;
+    this.apply(isDark);
+    this.persist(isDark ? "dark" : "light");
+  }
+  resolveTheme() {
+    const stored = this.read();
+    if (stored === "dark" || stored === "light")
+      return stored;
+    return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+  }
+  apply(isDark) {
+    document.documentElement.classList.toggle("dark", isDark);
+  }
+  read() {
+    try {
+      return window.localStorage.getItem(this.storageKeyValue);
+    } catch {
+      return null;
+    }
+  }
+  persist(theme) {
+    try {
+      window.localStorage.setItem(this.storageKeyValue, theme);
+    } catch {
+    }
+  }
+}
+
 function registerMidwestControllers(application) {
   application.register("midwest-card", Card);
   application.register("midwest-banner", Banner);
@@ -6590,6 +7025,10 @@ function registerMidwestControllers(application) {
   application.register("midwest-code-block", CodeBlock);
   application.register("midwest-date-picker", DatePicker);
   application.register("midwest-time-picker", TimePicker);
+  application.register("midwest-intersection-observer", ViewportObserver);
+  application.register("midwest-focus-trap", FocusTrap);
+  application.register("midwest-onboarding", Onboarding);
+  application.register("midwest-theme-switch", ThemeSwitch);
 }
 
 export { Banner, Card, Chart, CountdownTimer, registerMidwestControllers };