actual-css 0.1.0

package/src/js/tab.js

@@ -0,0 +1,173 @@
+/*
+ * Tabs — in-place panel switcher using real tab semantics.
+ *
+ * Tab list:  .tabs[role="tablist"]
+ * Tab:       [role="tab"]  with aria-selected, aria-controls, id, tabindex
+ * Panel:     [role="tabpanel"]  with id matching aria-controls
+ *
+ * Keyboard:  ArrowLeft/Right, Home/End (select tab, wrapping)
+ *            ArrowUp/Down for aria-orientation="vertical"
+ *            ArrowDown (focus selected panel)
+ *
+ * Self-registers via enhance: injected tablists wire automatically.
+ * The tab→panel map is rebuilt from the live tablist on each interaction,
+ * so tabs added after connect are picked up with no extra work.
+ * Cleanup is the AbortController.abort() returned to enhance.
+ */
+
+import enhance from "./enhance.js";
+import { firstItem, lastItem, nextItem } from "./keys.js";
+import { CLASSES } from "./selectors.js";
+
+const TABLIST_SELECTOR = `.${CLASSES.tabs}[role="tablist"]`;
+
+function tabsOf(list) {
+  return [...list.querySelectorAll('[role="tab"]')];
+}
+
+function panelsOf(tabs) {
+  const panels = new Map();
+  for (const tab of tabs) {
+    const panel = panelFor(tab);
+    if (panel) panels.set(tab, panel);
+  }
+  return panels;
+}
+
+function panelFor(tab) {
+  const panelId = tab.getAttribute("aria-controls");
+  return panelId ? document.getElementById(panelId) : null;
+}
+
+function isTabDisabled(tab) {
+  return tab.disabled || tab.getAttribute("aria-disabled") === "true";
+}
+
+function activatableTabs(list) {
+  return tabsOf(list).filter((tab) => !isTabDisabled(tab) && panelFor(tab));
+}
+
+function makePanelFocusable(panel) {
+  if (!panel.hasAttribute("tabindex")) {
+    panel.tabIndex = -1;
+  }
+}
+
+function activate(tab) {
+  if (!tab || isTabDisabled(tab) || !panelFor(tab)) return;
+  const list = tab.closest(TABLIST_SELECTOR);
+  if (!list) return;
+  const tabs = tabsOf(list);
+  const panels = panelsOf(tabs);
+
+  for (const t of tabs) {
+    t.setAttribute("aria-selected", "false");
+    t.tabIndex = -1;
+  }
+  for (const [, panel] of panels) {
+    panel.hidden = true;
+  }
+  tab.setAttribute("aria-selected", "true");
+  tab.tabIndex = 0;
+  const panel = panels.get(tab);
+  if (panel) {
+    makePanelFocusable(panel);
+    panel.hidden = false;
+  }
+}
+
+function activateAndFocus(tab) {
+  if (!tab) return;
+  activate(tab);
+  tab.focus();
+}
+
+function initialize(list) {
+  const tabs = activatableTabs(list);
+  if (!tabs.length) return;
+  const selected = tabs.find((tab) => tab.getAttribute("aria-selected") === "true") || tabs[0];
+  activate(selected);
+}
+
+function onKeydown(e) {
+  const tab = e.target.closest('[role="tab"]');
+  if (!tab) return;
+  const list = tab.closest(TABLIST_SELECTOR);
+  if (!list) return;
+
+  const tabs = activatableTabs(list);
+  if (!tabs.length || !tabs.includes(tab)) return;
+  const isVertical = list.getAttribute("aria-orientation") === "vertical";
+  let next;
+
+  switch (e.key) {
+    case "ArrowRight":
+      if (isVertical) break;
+      e.preventDefault();
+      next = nextItem(tabs, tab, 1, { wrap: true });
+      if (next) activateAndFocus(next);
+      break;
+    case "ArrowLeft":
+      if (isVertical) break;
+      e.preventDefault();
+      next = nextItem(tabs, tab, -1, { wrap: true });
+      if (next) activateAndFocus(next);
+      break;
+    case "ArrowDown":
+      if (!isVertical) {
+        e.preventDefault();
+        const panel = panelFor(tab);
+        if (panel) {
+          makePanelFocusable(panel);
+          panel.focus();
+        }
+        break;
+      }
+      e.preventDefault();
+      next = nextItem(tabs, tab, 1, { wrap: true });
+      if (next) activateAndFocus(next);
+      break;
+    case "ArrowUp":
+      if (!isVertical) break;
+      e.preventDefault();
+      next = nextItem(tabs, tab, -1, { wrap: true });
+      if (next) activateAndFocus(next);
+      break;
+    case "Home":
+      e.preventDefault();
+      activateAndFocus(firstItem(tabs));
+      break;
+    case "End":
+      e.preventDefault();
+      activateAndFocus(lastItem(tabs));
+      break;
+    case "Enter":
+    case " ":
+      e.preventDefault();
+      activate(tab);
+      break;
+  }
+}
+
+function onClick(e) {
+  const tab = e.target.closest('[role="tab"]');
+  if (!tab) return;
+  if (isTabDisabled(tab)) {
+    e.preventDefault();
+    return;
+  }
+  e.preventDefault();
+  if (tab.getAttribute("aria-selected") === "true") return;
+  activate(tab);
+  tab.focus();
+}
+
+enhance({
+  [TABLIST_SELECTOR]: (list) => {
+    const controller = new AbortController();
+    initialize(list);
+    list.addEventListener("click", onClick, { signal: controller.signal });
+    list.addEventListener("keydown", onKeydown, { signal: controller.signal });
+    return () => controller.abort();
+  },
+});

package/src/js/tooltip.js

@@ -0,0 +1,374 @@
+/*
+ * Tooltip — supplemental label shown on hover and focus.
+ *
+ * Shorthand:  <button data-tooltip="Help text" data-tooltip-placement="right">
+ * Explicit:   <button data-tooltip aria-describedby="tooltip-id">
+ *             <div role="tooltip" id="tooltip-id" hidden>Help <strong>text</strong></div>
+ * Options:    data-tooltip-click toggles on click instead of hover/focus.
+ *             data-tooltip-visible keeps the tooltip visible.
+ *
+ * Discovery:  [data-tooltip] only. An empty data-tooltip marks an explicit
+ *             tooltip that points at an aria-describedby target; a non-empty
+ *             data-tooltip generates the tooltip element lazily.
+ *             Plain aria-describedby (form help, error text) is never
+ *             treated as a tooltip trigger.
+ *
+ * Sharing:    an explicit tooltip may be referenced by several triggers. The
+ *             tooltip element is wired once (floating listeners + tracking);
+ *             each trigger only registers itself and the wiring is torn down
+ *             when the last trigger leaves the DOM.
+ *
+ * Lazy:       tooltip elements are created (shorthand) or wired (explicit) on
+ *             first mouseover / focusin. No page-load scan, no DOM overhead
+ *             for tooltips that are never triggered. AJAX-loaded triggers
+ *             work automatically via bubbling delegated listeners.
+ *
+ * Show:       hover + focus (150ms delay), click toggle, or always visible
+ * Hide:       blur, pointer leave, Escape
+ */
+
+import enhance from "./enhance.js";
+import { EVENTS } from "./events.js";
+import { reposition, track } from "./floating.js";
+import { CLASSES } from "./selectors.js";
+
+const SHOW_DELAY_MS = 150;
+const HIDE_DELAY_MS = 100;
+
+/**
+ * @typedef {object} TooltipState
+ * @property {Set<Element>} refs Triggers that currently reference this tip.
+ * @property {Element | null} activeRef Trigger that last showed this tip.
+ * @property {AbortController} controller Tip-level event listener cleanup.
+ * @property {() => void} untrack Floating-position cleanup.
+ * @property {boolean} generated True when the tip was created from data-tooltip text.
+ * @property {{ parent: Node, next: ChildNode | null } | null} mount Original DOM position for explicit tips moved into a dialog/body root.
+ * @property {ReturnType<typeof setTimeout> | null} timer Pending delayed show.
+ * @property {ReturnType<typeof setTimeout> | null} hideTimer Pending delayed hide.
+ * @property {boolean} overRef Pointer is over the active trigger.
+ * @property {boolean} overTip Pointer is over the tooltip.
+ */
+
+let uid = 0;
+const triggerStates = new WeakMap(); // trigger -> { tip, cleanup }
+/** @type {WeakMap<Element, TooltipState>} */
+const tipStates = new WeakMap(); // tip -> { refs, activeRef, controller, untrack, generated, mount, timer }
+
+function mountTip(tip, trigger) {
+  const root = trigger.closest("dialog") || trigger.ownerDocument.body;
+  const parent = tip.parentNode;
+  if (!root || !parent || parent === root) return null;
+
+  const mount = { parent, next: tip.nextSibling };
+  root.append(tip);
+  return mount;
+}
+
+function restoreTip(tip, state) {
+  const mount = state.mount;
+  if (!mount) return;
+
+  if (mount.parent.isConnected) {
+    const next = mount.next?.parentNode === mount.parent ? mount.next : null;
+    mount.parent.insertBefore(tip, next);
+  } else {
+    tip.remove();
+  }
+}
+
+function placementFor(ref) {
+  return ref?.getAttribute("data-tooltip-placement") || "top";
+}
+
+function hasOption(trigger, name) {
+  const value = trigger?.getAttribute(name);
+  return value !== null && value.toLowerCase() !== "false";
+}
+
+function isClickTrigger(trigger) {
+  return hasOption(trigger, "data-tooltip-click");
+}
+
+function isAlwaysVisible(trigger) {
+  return hasOption(trigger, "data-tooltip-visible");
+}
+
+function describedByIds(trigger) {
+  return (trigger.getAttribute("aria-describedby") || "").split(/\s+/).filter(Boolean);
+}
+
+function addDescription(trigger, id) {
+  const ids = describedByIds(trigger);
+  if (ids.includes(id)) return false;
+  trigger.setAttribute("aria-describedby", [...ids, id].join(" "));
+  return true;
+}
+
+function removeDescription(trigger, id) {
+  const ids = describedByIds(trigger).filter((candidate) => candidate !== id);
+  if (ids.length) {
+    trigger.setAttribute("aria-describedby", ids.join(" "));
+  } else {
+    trigger.removeAttribute("aria-describedby");
+  }
+}
+
+function explicitTipFor(trigger) {
+  const doc = trigger.ownerDocument;
+  for (const id of describedByIds(trigger)) {
+    const candidate = doc.getElementById(id);
+    if (candidate?.getAttribute("role") === "tooltip") return candidate;
+  }
+  return null;
+}
+
+function nextTooltipId(doc) {
+  let id;
+  do {
+    uid++;
+    id = `tooltip-${uid}`;
+  } while (doc.getElementById(id));
+  return id;
+}
+
+function repositionTip(ref, tip) {
+  reposition(ref, tip, {
+    placement: placementFor(ref),
+    distance: 6,
+    flip: true,
+    shift: true,
+  });
+}
+
+function hideTip(tip, force = false) {
+  const state = tipStates.get(tip);
+  if (!force && isAlwaysVisible(state?.activeRef)) return;
+  if (state?.timer) {
+    clearTimeout(state.timer);
+    state.timer = null;
+  }
+  if (state?.hideTimer) {
+    clearTimeout(state.hideTimer);
+    state.hideTimer = null;
+  }
+  tip.hidden = true;
+}
+
+function clearHide(tip) {
+  const state = tipStates.get(tip);
+  if (!state?.hideTimer) return;
+  clearTimeout(state.hideTimer);
+  state.hideTimer = null;
+}
+
+function scheduleHide(tip) {
+  const state = tipStates.get(tip);
+  if (!state) return;
+  if (isClickTrigger(state.activeRef) || isAlwaysVisible(state.activeRef)) return;
+  if (state.overRef || state.overTip) return;
+  if (state.hideTimer) clearTimeout(state.hideTimer);
+  state.hideTimer = setTimeout(() => {
+    state.hideTimer = null;
+    if (!state.overRef && !state.overTip) hideTip(tip);
+  }, HIDE_DELAY_MS);
+}
+
+// Tip-level wiring happens once per tooltip element, even when an explicit
+// tooltip is shared by several triggers. activeRef is the trigger that last
+// showed the tip, so reposition follows the right reference.
+function wireTip(tip, options = {}) {
+  let state = tipStates.get(tip);
+  if (state) return state;
+
+  const controller = new AbortController();
+  state = {
+    refs: new Set(),
+    activeRef: null,
+    controller,
+    untrack: track(tip),
+    generated: options.generated === true,
+    mount: options.mount || null,
+    timer: null,
+    hideTimer: null,
+    overRef: false,
+    overTip: false,
+  };
+
+  const onHide = () => hideTip(tip);
+  const onOutOfView = () => hideTip(tip, true);
+  const onReposition = () => {
+    if (isAlwaysVisible(state.activeRef)) tip.hidden = false;
+    if (!tip.hidden && state.activeRef) repositionTip(state.activeRef, tip);
+  };
+
+  tip.addEventListener(EVENTS.reposition, onReposition, { signal: controller.signal });
+  tip.addEventListener(EVENTS.hide, onHide, { signal: controller.signal });
+  tip.addEventListener(EVENTS.outOfView, onOutOfView, { signal: controller.signal });
+  tip.addEventListener(
+    "mouseenter",
+    () => {
+      state.overTip = true;
+      clearHide(tip);
+    },
+    { signal: controller.signal },
+  );
+  tip.addEventListener(
+    "mouseleave",
+    () => {
+      state.overTip = false;
+      scheduleHide(tip);
+    },
+    { signal: controller.signal },
+  );
+
+  tipStates.set(tip, state);
+  return state;
+}
+
+function ensureTip(trigger) {
+  const existing = triggerStates.get(trigger);
+  if (existing) return existing.tip;
+
+  let tip;
+  let generated = false;
+  let mount = null;
+  let descriptionAdded = false;
+  const text = trigger.getAttribute("data-tooltip");
+  const doc = trigger.ownerDocument;
+
+  // shorthand: data-tooltip="text" → create element lazily
+  if (text) {
+    tip = doc.createElement("div");
+    tip.className = CLASSES.tooltip;
+    tip.role = "tooltip";
+    tip.id = nextTooltipId(doc);
+    tip.textContent = text;
+    tip.hidden = true;
+    tip.style.position = "fixed";
+    generated = true;
+
+    const parent = trigger.closest("dialog") || doc.body;
+    parent.appendChild(tip);
+    descriptionAdded = addDescription(trigger, tip.id);
+  }
+
+  // explicit: data-tooltip (empty) + aria-describedby → find existing element
+  if (!tip) {
+    tip = explicitTipFor(trigger);
+    if (!tip) return null;
+    tip.hidden = true;
+    tip.style.position = "fixed";
+
+    if (!tipStates.has(tip)) {
+      mount = mountTip(tip, trigger);
+    }
+  }
+
+  const state = wireTip(tip, { generated, mount });
+  state.refs.add(trigger);
+
+  const triggerController = new AbortController();
+  const onLeave = () => {
+    state.overRef = false;
+    scheduleHide(tip);
+  };
+  trigger.addEventListener("mouseleave", onLeave, { signal: triggerController.signal });
+  trigger.addEventListener("blur", onLeave, { signal: triggerController.signal });
+
+  const cleanup = () => {
+    triggerController.abort();
+    triggerStates.delete(trigger);
+    if (descriptionAdded) removeDescription(trigger, tip.id);
+
+    state.refs.delete(trigger);
+    if (state.activeRef === trigger) {
+      hideTip(tip, true);
+      state.activeRef = null;
+    }
+    // Other triggers still share this tooltip: keep the tip wiring alive.
+    if (state.refs.size > 0) return;
+
+    hideTip(tip, true);
+    state.controller.abort();
+    state.untrack();
+    tipStates.delete(tip);
+    if (state.generated) tip.remove();
+    else restoreTip(tip, state);
+  };
+
+  triggerStates.set(trigger, { tip, cleanup });
+  return tip;
+}
+
+function cleanupTrigger(trigger) {
+  if (trigger.isConnected) return;
+  triggerStates.get(trigger)?.cleanup?.();
+}
+
+function show(tip, ref, immediate = false) {
+  const state = tipStates.get(tip);
+  if (!state) return;
+
+  state.activeRef = ref;
+  state.overRef = true;
+  clearHide(tip);
+  if (state.timer) clearTimeout(state.timer);
+  const reveal = () => {
+    state.timer = null;
+    tip.hidden = false;
+    repositionTip(ref, tip);
+  };
+
+  if (immediate) reveal();
+  else state.timer = setTimeout(reveal, SHOW_DELAY_MS);
+}
+
+// ── Delegated discovery (mouseover + focusin bubble) ───
+
+const SEL = "[data-tooltip]";
+
+function handleTriggerIntent(e) {
+  const trigger = e.target.closest?.(SEL);
+  if (!trigger) return;
+  if (isClickTrigger(trigger) || isAlwaysVisible(trigger)) return;
+  if (
+    e.type === "mouseover" &&
+    e.relatedTarget instanceof Node &&
+    trigger.contains(e.relatedTarget)
+  )
+    return;
+
+  const tip = ensureTip(trigger);
+  if (tip) show(tip, trigger);
+}
+
+function handleTriggerClick(e) {
+  const trigger = e.target.closest?.(SEL);
+  if (!trigger || !isClickTrigger(trigger) || isAlwaysVisible(trigger)) return;
+
+  const tip = ensureTip(trigger);
+  if (!tip) return;
+
+  e.preventDefault();
+  if (tip.hidden) show(tip, trigger, true);
+  else hideTip(tip, true);
+}
+
+// Delegated discovery listeners run at import time; keep SSR imports inert.
+if (typeof document !== "undefined") {
+  document.addEventListener("mouseover", handleTriggerIntent);
+  document.addEventListener("focusin", handleTriggerIntent);
+  document.addEventListener("click", handleTriggerClick);
+
+  enhance({
+    [SEL]: (trigger) => {
+      // Ordinary and click-triggered tooltips stay lazy. The always-visible
+      // option necessarily opts into eager creation/wiring.
+      if (isAlwaysVisible(trigger)) {
+        const tip = ensureTip(trigger);
+        if (tip) show(tip, trigger, true);
+      }
+      return () => cleanupTrigger(trigger);
+    },
+  });
+}