actual-css 0.1.0 → 0.3.0

package/src/js/scrollspy.js

@@ -1,22 +1,39 @@
 /*
  * Scrollspy — navigation that highlights the active section on scroll.
  *
- * Nav:    .scrollspy containing <a href="#section-id"> links
+ * Nav:    [data-enhance="scrollspy"] containing <a href="#section-id"> links
  * Target: elements referenced by the href fragments
  *
- * Uses IntersectionObserver. Falls back gracefully: links still work
- * even if IntersectionObserver isn't available.
+ * Deterministic geometry, not IntersectionObserver: on each scroll (throttled
+ * with requestAnimationFrame) the active section is the last one whose top has
+ * crossed an activation line. An IntersectionObserver reports *which* sections
+ * intersect, not which one is current, so it has to guess whenever several
+ * share the viewport — and guesses wrong for sections shorter than the band.
  *
- * Optional root: data-scrollspy-root="#scroll-container" observes section
- * visibility within a scroll container instead of the viewport.
+ * activation line = root top + offset      (default 20% of the root's height)
+ * active section  = last section whose top <= activation line
+ * scrolled to end = last section, whatever the line says
+ * above the first = no active section
  *
- * Self-registers via enhance: injected .scrollspy navs wire automatically.
- * Cleanup disconnects the IntersectionObserver and the small MutationObserver
- * that refreshes the link→section map as nav links or sections are injected.
+ * Optional root: data-scrollspy-root="#scroll-container" measures against a
+ * scroll container instead of the viewport.
+ * Optional offset: data-scrollspy-offset="24" | "24px" | "20%" moves the
+ * activation line. Invalid values fall back to 20%; negatives clamp to 0.
+ *
+ * Self-registers via registerEnhancement: injected navs wire automatically.
+ * Cleanup removes the scroll/resize listeners and the small MutationObserver
+ * that refreshes the link->section map as nav links are injected. New sections
+ * outside the nav subtree are not observed — call refreshScrollspy(nav) after
+ * those mutations.
+ *
+ * The .scrollspy class alone still gives :target-current behavior via CSS —
+ * a documented no-JS mode, not a fallback remark.
  */
 
-import enhance from "./enhance.js";
-import { CLASSES } from "./selectors.js";
+import { registerEnhancement } from "./enhance.js";
+
+const DEFAULT_OFFSET_RATIO = 0.2;
+const navState = new WeakMap();
 
 function rootFor(nav) {
   const selector = nav.getAttribute("data-scrollspy-root");
@@ -42,80 +59,134 @@ function sectionsFor(nav) {
   return sections;
 }
 
-const navState = new WeakMap();
+/*
+ * Viewport-relative measurements for either scroll root. The window branch
+ * reads documentElement rather than a captured window so a nav in another
+ * document measures its own root — same reason surface.js resolves
+ * ownerDocument instead of binding at import time.
+ */
+function measureRoot(nav, root) {
+  if (root) {
+    return {
+      top: root.getBoundingClientRect().top,
+      height: root.clientHeight,
+      scrollTop: root.scrollTop,
+      scrollHeight: root.scrollHeight,
+    };
+  }
 
-export function refreshScrollspy(nav) {
-  navState.get(nav)?.rebuild();
+  // scrollingElement is the real scroll container in standards mode; fall
+  // back to documentElement (quirks mode, or older engines without it).
+  const doc = nav.ownerDocument;
+  const el = doc.scrollingElement || doc.documentElement;
+  return {
+    top: 0,
+    height: el.clientHeight,
+    scrollTop: el.scrollTop,
+    scrollHeight: el.scrollHeight,
+  };
+}
+
+/*
+ * "24" and "24px" are pixels, "20%" is a share of the root's visible height.
+ * Percentages resolve per measurement, so a resize needs no rebuild.
+ */
+function activationOffset(nav, height) {
+  const raw = (nav.getAttribute("data-scrollspy-offset") ?? "").trim();
+  if (!raw) return height * DEFAULT_OFFSET_RATIO;
+
+  const value = Number.parseFloat(raw);
+  if (!Number.isFinite(value)) return height * DEFAULT_OFFSET_RATIO;
+
+  return Math.max(0, raw.endsWith("%") ? (height * value) / 100 : value);
 }
 
 function setupNav(nav) {
-  if (typeof IntersectionObserver === "undefined") return;
-  let io = null;
+  const controller = new AbortController();
   let sections = [];
-  const activeEntries = new Map();
-  let scheduled = false;
+  let frame = 0;
+  let current;
+
+  function activate(section) {
+    if (section === current) return;
+    current = section;
+
+    for (const entry of sections) {
+      if (entry.section === section) {
+        entry.link.setAttribute("aria-current", "location");
+      } else {
+        entry.link.removeAttribute("aria-current");
+      }
+    }
+  }
 
-  function rebuild() {
-    scheduled = false;
-    io?.disconnect();
-    sections = sectionsFor(nav);
-    activeEntries.clear();
+  function measure() {
+    frame = 0;
     if (!sections.length) return;
 
-    io = new IntersectionObserver(
-      (entries) => {
-        for (const entry of entries) {
-          if (entry.isIntersecting) {
-            activeEntries.set(entry.target, entry);
-          } else {
-            activeEntries.delete(entry.target);
-          }
-        }
-
-        const visible = [...activeEntries.values()].sort(
-          (a, b) => a.boundingClientRect.top - b.boundingClientRect.top,
-        );
-
-        const id = visible[0]?.target.id;
-        for (const { link } of sections) {
-          if (id && link.getAttribute("href") === `#${id}`) {
-            link.setAttribute("aria-current", "location");
-          } else {
-            link.removeAttribute("aria-current");
-          }
-        }
-      },
-      {
-        root: rootFor(nav),
-        rootMargin: "-20% 0px -70% 0px",
-        threshold: 0,
-      },
-    );
+    const root = rootFor(nav);
+    const { top, height, scrollTop, scrollHeight } = measureRoot(nav, root);
+
+    // Scrolled to the end: the last section wins even when its top never
+    // crosses the line. This is the case IntersectionObserver cannot express.
+    if (scrollHeight > height && scrollTop + height >= scrollHeight - 1) {
+      activate(sections.at(-1).section);
+      return;
+    }
 
+    const line = top + activationOffset(nav, height);
+    let active = null;
     for (const { section } of sections) {
-      io.observe(section);
+      if (section.getBoundingClientRect().top <= line) active = section;
     }
+
+    activate(active);
   }
 
-  function scheduleRebuild() {
-    if (scheduled) return;
-    scheduled = true;
-    queueMicrotask(rebuild);
+  function schedule(run = measure) {
+    if (frame) cancelAnimationFrame(frame);
+    frame = requestAnimationFrame(run);
   }
 
-  const mo = new MutationObserver(scheduleRebuild);
+  function rebuild() {
+    sections = sectionsFor(nav);
+    current = undefined;
+    measure();
+  }
+
+  // The scroll root (custom container or the document viewport) is resolved
+  // once at connect and is stable for the lifetime of the connection; measure
+  // still re-reads the current root element so a replaced *element* under a
+  // stable container is handled, but swapping the container itself is out of
+  // contract (re-inject the nav or call refreshScrollspy after such a move).
+  const scrollTarget = rootFor(nav) ?? nav.ownerDocument.defaultView;
+  scrollTarget?.addEventListener("scroll", () => schedule(), {
+    passive: true,
+    signal: controller.signal,
+  });
+  nav.ownerDocument.defaultView?.addEventListener("resize", () => schedule(), {
+    passive: true,
+    signal: controller.signal,
+  });
+
+  // Observer is scoped to the nav subtree — link injection is caught;
+  // section-only DOM mutations elsewhere need an explicit refreshScrollspy().
+  const mo = new MutationObserver(() => schedule(rebuild));
   mo.observe(nav, { childList: true, subtree: true });
-  navState.set(nav, { rebuild: scheduleRebuild });
+  navState.set(nav, { rebuild });
 
   rebuild();
 
   return () => {
-    io?.disconnect();
+    controller.abort();
+    if (frame) cancelAnimationFrame(frame);
     mo.disconnect();
     navState.delete(nav);
   };
 }
 
-enhance({
-  [`.${CLASSES.scrollspy}`]: setupNav,
-});
+export function refreshScrollspy(nav) {
+  navState.get(nav)?.rebuild();
+}
+
+registerEnhancement("scrollspy", setupNav);

package/src/js/selectors.js

@@ -1,35 +1,29 @@
 /*
- * Selectors — the CSS class names this runtime looks for or writes, gathered
- * in one file.
+ * Selectors — the state-class vocabulary the runtime writes.
  *
- * Every module that matches against or toggles one of Actual's own class
- * names imports its token from here instead of writing the string inline.
- * To run this runtime against a different CSS framework, edit this file (or
- * alias it in a bundler) — no other module needs to change.
+ * This file no longer lists discovery selectors: behavior discovery moved
+ * to data-enhance tokens in 0.2. What remains are the class names modules
+ * write as state (is-open, was-validated, …) and validation's two read-side
+ * presentation adapters (field, fieldError). To run this runtime against a
+ * different CSS framework, edit this file (or alias it in a bundler).
  *
  * data-* attributes and ARIA are not listed: they are each module's own
  * behavior API, not CSS vocabulary, so they stay framework-neutral by
- * construction and never need remapping. A module with no entry here (see
- * status.js) has no CSS class dependency at all.
+ * construction and never need remapping.
  */
+
 export const CLASSES = {
-  // flyout.js, context-menu.js — opt-in class on the panel/menu element.
-  flyout: "flyout",
-  // tab.js — opt-in class on the tablist element.
-  tabs: "tabs",
-  // scrollspy.js — opt-in class on the nav element.
-  scrollspy: "scrollspy",
-  // validation.js — opt-in class on the <form>.
-  needsValidation: "needs-validation",
   // validation.js — written on <form> after the first submit attempt.
   wasValidated: "was-validated",
-  // validation.js — read on the element an aria-describedby id resolves to.
-  fieldError: "field-error",
-  // validation.js — ancestor container searched for aria-invalid/danger state.
-  field: "field",
   // validation.js — intents.css vocabulary class toggled on the field
   // container while any control inside it is invalid.
   danger: "danger",
+  // validation.js — read-side presentation adapter: error slot among
+  // aria-describedby targets. [data-field-error] is an accepted alias (D6).
+  fieldError: "field-error",
+  // validation.js — read-side presentation adapter: ancestor container
+  // for aria-invalid/danger state. Optional — degrades to no-op.
+  field: "field",
   // surface.js — state class on the open flyout/menu/dialog surface.
   open: "is-open",
   // surface.js — state class while the surface renders as a mobile sheet.
@@ -38,13 +32,6 @@ export const CLASSES = {
   backdrop: "surface-backdrop",
   // dialog.js — transient class for the "can't dismiss" shake animation.
   static: "is-static",
-  // dialog-fallback.js — marker written on a dialog controlled by the legacy
-  // shim (browsers without native <dialog>); dialog-fallback.css keys its
-  // emulated dialog presentation on it.
-  dialogFallback: "dialog-fallback",
-  // dialog-fallback.js — state class on a shimmed dialog while it is open as
-  // a modal; carries the fixed positioning and simulated backdrop.
-  fallbackModal: "is-fallback-modal",
   // dialog.js — written on <html> while any modal dialog is open.
   modalOpen: "has-modal-open",
   // dialog.js — written on <html> when the viewport had a classic scrollbar
@@ -52,8 +39,4 @@ export const CLASSES = {
   hadScrollbar: "had-scrollbar",
   // tooltip.js — class name written on a shorthand-generated tooltip element.
   tooltip: "tooltip",
-  // status.js — required alongside [data-status]. "status" is a common
-  // domain word (order status, task status, …); the class keeps a
-  // document-wide querySelector from matching an unrelated app element.
-  statusBar: "status-bar",
 };

package/src/js/status.js

@@ -24,23 +24,23 @@
  *   - Any other code, without importing this module: dispatch `actual:status`
  *     directly — `detail: { message, intent, duration }`, or `{}` to clear.
  *
- * The element contract is `.status-bar[data-status]`. Both are required:
- * "status" is a generic domain word, so the class keeps the document-wide
- * lookup from matching an unrelated app element that happens to carry its own
- * `data-status`. `intent` is applied verbatim as one or more classes on the
- * target (space-separated for more than one, e.g. "danger uppercase").
- * status.js does not know or validate any specific names — .danger, .success,
- * and friends are Actual's own intents.css vocabulary, not something this
- * module hardcodes. Each call removes the intent classes the previous call
- * added (tracked in data-status-classes on the target itself), then adds the
- * current call's, so stale intent classes never accumulate and classes the
- * app added independently are left alone.
+ * The element contract is `[data-status][role="status"]`. Both are required:
+ * "status" is a generic domain word, so `role="status"` keeps the
+ * document-wide lookup from matching an unrelated app element that happens to
+ * carry its own `data-status`. `intent` is applied verbatim as one or more
+ * classes on the target (space-separated for more than one, e.g. "danger
+ * uppercase"). status.js does not know or validate any specific names —
+ * .danger, .success, and friends are Actual's own intents.css vocabulary, not
+ * something this module hardcodes. Each call removes the intent classes the
+ * previous call added (tracked in data-status-classes on the target itself),
+ * then adds the current call's, so stale intent classes never accumulate and
+ * classes the app added independently are left alone.
  */
+
 import { registerCommands, targetFor } from "./command.js";
 import { EVENTS } from "./events.js";
-import { CLASSES } from "./selectors.js";
 
-const STATUS_SELECTOR = `.${CLASSES.statusBar}[data-status]`;
+const STATUS_SELECTOR = '[data-status][role="status"]';
 const STATUS_CLASSES_ATTR = "statusClasses";
 
 let statusTimer;
@@ -125,7 +125,9 @@ if (typeof document !== "undefined") {
   // importing this module. A message shows it; omitting one clears it.
   document.addEventListener(EVENTS.status, (event) => {
     const { message, intent, duration } = event.detail ?? {};
-    if (message) {
+    // `message != null` keeps "" (an intentional empty message) on the show
+    // path, consistent with status() itself; an absent message clears.
+    if (message != null) {
       status(message, { intent, duration });
     } else {
       status.clear();