actual-css 0.1.0

package/src/js/scrollspy.js

@@ -0,0 +1,121 @@
+/*
+ * Scrollspy — navigation that highlights the active section on scroll.
+ *
+ * Nav:    .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.
+ *
+ * Optional root: data-scrollspy-root="#scroll-container" observes section
+ * visibility within a scroll container instead of the viewport.
+ *
+ * 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.
+ */
+
+import enhance from "./enhance.js";
+import { CLASSES } from "./selectors.js";
+
+function rootFor(nav) {
+  const selector = nav.getAttribute("data-scrollspy-root");
+  if (!selector) return null;
+
+  try {
+    return nav.ownerDocument.querySelector(selector);
+  } catch {
+    return null;
+  }
+}
+
+function sectionsFor(nav) {
+  const links = [...nav.querySelectorAll("a[href^='#']")];
+  const sections = [];
+
+  for (const link of links) {
+    const id = link.getAttribute("href").slice(1);
+    const section = id ? nav.ownerDocument.getElementById(id) : null;
+    if (section) sections.push({ link, section });
+  }
+
+  return sections;
+}
+
+const navState = new WeakMap();
+
+export function refreshScrollspy(nav) {
+  navState.get(nav)?.rebuild();
+}
+
+function setupNav(nav) {
+  if (typeof IntersectionObserver === "undefined") return;
+  let io = null;
+  let sections = [];
+  const activeEntries = new Map();
+  let scheduled = false;
+
+  function rebuild() {
+    scheduled = false;
+    io?.disconnect();
+    sections = sectionsFor(nav);
+    activeEntries.clear();
+    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,
+      },
+    );
+
+    for (const { section } of sections) {
+      io.observe(section);
+    }
+  }
+
+  function scheduleRebuild() {
+    if (scheduled) return;
+    scheduled = true;
+    queueMicrotask(rebuild);
+  }
+
+  const mo = new MutationObserver(scheduleRebuild);
+  mo.observe(nav, { childList: true, subtree: true });
+  navState.set(nav, { rebuild: scheduleRebuild });
+
+  rebuild();
+
+  return () => {
+    io?.disconnect();
+    mo.disconnect();
+    navState.delete(nav);
+  };
+}
+
+enhance({
+  [`.${CLASSES.scrollspy}`]: setupNav,
+});

package/src/js/selectors.js

@@ -0,0 +1,59 @@
+/*
+ * Selectors — the CSS class names this runtime looks for or writes, gathered
+ * in one file.
+ *
+ * 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.
+ *
+ * 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.
+ */
+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",
+  // 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.
+  sheet: "is-sheet",
+  // surface.js — class name written on the generated sheet backdrop.
+  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
+  // before the first modal lock.
+  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

@@ -0,0 +1,158 @@
+/*
+ * Status — singleton floating status bar.
+ *
+ * A status bar is a transient, non-critical feedback area. Keep one element in
+ * the HTML, empty by default; JavaScript only updates its text content. It is
+ * hidden visually when empty but stays available as a live region.
+ *
+ * Importing the module auto-wires it to Actual's validation: a form that fails
+ * to submit shows its data-validation-message in the status bar. The bar is a
+ * view, not a validation mechanism, so validation and status stay decoupled.
+ *
+ *   import "actual-css/js/status";
+ *
+ * Three ways to trigger it, all funneling through the same `actual:status`
+ * event so any of them can be observed the same way:
+ *
+ *   - Programmatic (bundlers, third-party code): `import { status } from
+ *     "actual-css/js/status"`, then `status()` / `status.clear()`.
+ *   - Declarative, no JS required beyond the runtime:
+ *     <button commandfor="app-status" command="--status"
+ *             data-status-message="Saved." data-status-intent="success">
+ *     <button commandfor="app-status" command="--status-clear">
+ *     (the status bar element itself needs the matching `id="app-status"`.)
+ *   - 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.
+ */
+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_CLASSES_ATTR = "statusClasses";
+
+let statusTimer;
+
+function statusTarget() {
+  if (typeof document === "undefined") return null;
+  return document.querySelector(STATUS_SELECTOR);
+}
+
+function intentClasses(value) {
+  return typeof value === "string" ? value.trim().split(/\s+/).filter(Boolean) : [];
+}
+
+function clearIntentClasses(target) {
+  const previous = target.dataset[STATUS_CLASSES_ATTR];
+  if (previous) {
+    target.classList.remove(...previous.split(" "));
+  }
+  delete target.dataset[STATUS_CLASSES_ATTR];
+}
+
+export function status(message, options = {}) {
+  const target = statusTarget();
+  if (!target || message == null) return;
+
+  clearTimeout(statusTimer);
+
+  clearIntentClasses(target);
+  const intent = intentClasses(options.intent);
+  if (intent.length) {
+    target.classList.add(...intent);
+    target.dataset[STATUS_CLASSES_ATTR] = intent.join(" ");
+  }
+
+  target.textContent = message;
+
+  if (options.duration !== false) {
+    statusTimer = setTimeout(() => status.clear(), options.duration ?? 3000);
+  }
+}
+
+status.clear = function clear() {
+  const target = statusTarget();
+  if (target) {
+    target.textContent = "";
+    clearIntentClasses(target);
+  }
+  clearTimeout(statusTimer);
+};
+
+const STATUS_SHOW_COMMANDS = ["--status"];
+const STATUS_CLEAR_COMMANDS = ["--status-clear"];
+
+function dispatchStatusEvent(source, detail) {
+  source.dispatchEvent(new CustomEvent(EVENTS.status, { bubbles: true, detail }));
+}
+
+function readDuration(trigger) {
+  const raw = trigger.getAttribute("data-status-duration");
+  if (raw === null) return undefined;
+  if (raw === "false") return false;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function resolveStatusTrigger(trigger) {
+  const target = targetFor(trigger);
+  return target && target === statusTarget() ? target : null;
+}
+
+function connectStatusTrigger(trigger, target) {
+  trigger.setAttribute("aria-controls", target.id);
+}
+
+if (typeof document !== "undefined") {
+  document.addEventListener(EVENTS.invalid, (event) => {
+    const message = event.detail?.message;
+    if (message) status(message, { intent: "danger" });
+  });
+
+  // Public contract: any code can trigger the status bar this way, without
+  // importing this module. A message shows it; omitting one clears it.
+  document.addEventListener(EVENTS.status, (event) => {
+    const { message, intent, duration } = event.detail ?? {};
+    if (message) {
+      status(message, { intent, duration });
+    } else {
+      status.clear();
+    }
+  });
+
+  registerCommands(STATUS_SHOW_COMMANDS, {
+    resolve: resolveStatusTrigger,
+    prepare: connectStatusTrigger,
+    handle: (event, trigger) => {
+      event.preventDefault();
+      dispatchStatusEvent(trigger, {
+        message: trigger.getAttribute("data-status-message"),
+        intent: trigger.getAttribute("data-status-intent") ?? undefined,
+        duration: readDuration(trigger),
+      });
+    },
+  });
+
+  registerCommands(STATUS_CLEAR_COMMANDS, {
+    resolve: resolveStatusTrigger,
+    prepare: connectStatusTrigger,
+    handle: (event, trigger) => {
+      event.preventDefault();
+      dispatchStatusEvent(trigger, {});
+    },
+  });
+}
+
+export default status;

package/src/js/surface.js

@@ -0,0 +1,358 @@
+import { EVENTS } from "./events.js";
+import { reposition, repositionAt, track } from "./floating.js";
+import { hasMenuItem, onMenuKeydown } from "./menu.js";
+import { CLASSES } from "./selectors.js";
+
+const DEFAULT_BREAKPOINT = 768;
+const BREAKPOINTS = {
+  sm: 640,
+  md: 768,
+  lg: 1024,
+};
+const openSurfaces = new Set();
+const surfaceMap = new WeakMap();
+const mountedSurfaces = new WeakMap();
+
+function waitForAnimations(...elements) {
+  const animations = elements
+    .filter(Boolean)
+    .flatMap((el) =>
+      typeof el.getAnimations === "function" ? el.getAnimations({ subtree: true }) : [],
+    );
+
+  return Promise.allSettled(animations.map((animation) => animation.finished));
+}
+
+function getSurfaceRoot(menu, anchor) {
+  return anchor?.closest("dialog") || menu.closest("dialog") || menu.ownerDocument.body;
+}
+
+function mountSurface(menu, anchor) {
+  if (mountedSurfaces.has(menu)) return;
+
+  const root = getSurfaceRoot(menu, anchor);
+  const parent = menu.parentNode;
+  if (!root || !parent || parent === root) return;
+
+  mountedSurfaces.set(menu, { parent, next: menu.nextSibling });
+  root.append(menu);
+}
+
+function restoreSurface(menu) {
+  const mount = mountedSurfaces.get(menu);
+  if (!mount) return;
+
+  if (mount.parent.isConnected) {
+    const next = mount.next?.parentNode === mount.parent ? mount.next : null;
+    mount.parent.insertBefore(menu, next);
+  } else {
+    menu.remove();
+  }
+
+  mountedSurfaces.delete(menu);
+}
+
+function getBreakpoint(menu) {
+  const value = menu.dataset.flyoutBreakpoint || "";
+  const raw = Number.parseInt(BREAKPOINTS[value] || value, 10);
+  return Number.isFinite(raw) ? raw : DEFAULT_BREAKPOINT;
+}
+
+function getMobileMode(menu, mode) {
+  return mode || menu.dataset.flyoutMobile || "auto";
+}
+
+function getPlacement(menu, placement) {
+  return placement || menu.dataset.flyoutPlacement || "bottom-start";
+}
+
+function getDistance(menu, distance) {
+  if (distance != null) return distance;
+  const value = Number.parseFloat(menu.dataset.flyoutDistance);
+  return Number.isFinite(value) ? value : 4;
+}
+
+function getAutoCloseMode(menu, value) {
+  const mode = String(value ?? menu.dataset.flyoutAutoClose ?? "true").toLowerCase();
+  if (mode === "inside" || mode === "outside" || mode === "false") return mode;
+  return "true";
+}
+
+function shouldUseSheet(menu, mode) {
+  const mobile = getMobileMode(menu, mode);
+  if (mobile === "none" || mobile === "anchored") return false;
+  if (mobile === "sheet") return true;
+
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return false;
+  }
+
+  const breakpoint = getBreakpoint(menu);
+  return (
+    window.matchMedia("(pointer: coarse)").matches &&
+    window.matchMedia(`(max-width: ${breakpoint}px)`).matches
+  );
+}
+
+function linkedTriggers(menu) {
+  if (!menu.id) return [];
+  return [...menu.ownerDocument.querySelectorAll(`[aria-controls="${CSS.escape(menu.id)}"]`)];
+}
+
+function syncExpanded(menu, expanded) {
+  for (const trigger of linkedTriggers(menu)) {
+    trigger.setAttribute("aria-expanded", expanded ? "true" : "false");
+  }
+}
+
+function ensureBackdrop(menu, state) {
+  if (!state.isSheet) {
+    state.backdrop?.remove();
+    state.backdrop = null;
+    return;
+  }
+
+  if (state.backdrop?.isConnected) {
+    state.backdrop.hidden = false;
+    return;
+  }
+
+  const backdrop = menu.ownerDocument.createElement("div");
+  backdrop.className = CLASSES.backdrop;
+  backdrop.hidden = false;
+  backdrop.addEventListener("click", () => {
+    closeSurface(menu);
+  });
+
+  menu.before(backdrop);
+  state.backdrop = backdrop;
+}
+
+function applyPresentation(menu, state) {
+  state.isSheet = shouldUseSheet(menu, state.mobile);
+  if (state.isSheet) {
+    menu.style.removeProperty("left");
+    menu.style.removeProperty("top");
+  }
+  menu.classList.toggle(CLASSES.sheet, state.isSheet);
+  ensureBackdrop(menu, state);
+}
+
+function positionSurface(menu) {
+  const state = surfaceMap.get(menu);
+  if (!state || state.isSheet) return;
+
+  if (state.trigger) {
+    const triggerWidth = state.trigger.getBoundingClientRect().width;
+    menu.style.setProperty("--flyout-trigger-width", `${triggerWidth}px`);
+  } else {
+    menu.style.removeProperty("--flyout-trigger-width");
+  }
+
+  const opts = {
+    placement: state.placement || "bottom-start",
+    distance: state.distance ?? 4,
+    flip: state.flip !== false,
+    shift: state.shift !== false,
+    shiftPadding: state.shiftPadding ?? 4,
+    scope: state.scope,
+  };
+
+  if (state.point) {
+    repositionAt(state.point.x, state.point.y, menu, opts);
+    return;
+  }
+
+  const anchor = state.trigger || state.source;
+  if (anchor) reposition(anchor, menu, opts);
+}
+
+function ensureSurfaceWired(menu) {
+  if (surfaceMap.has(menu)) return surfaceMap.get(menu);
+
+  const controller = new AbortController();
+  const state = {
+    controller,
+    untrack: track(menu),
+    backdrop: null,
+    trigger: null,
+    source: null,
+    point: null,
+    mobile: "auto",
+    placement: "bottom-start",
+    distance: 4,
+    flip: true,
+    shift: true,
+    shiftPadding: 4,
+    autoClose: "true",
+    isSheet: false,
+    closeId: 0,
+  };
+
+  menu.addEventListener(
+    EVENTS.reposition,
+    (e) => {
+      if (menu.hidden) return;
+      if (e.detail?.type === "scroll" && surfaceMap.get(menu)?.point) {
+        closeSurface(menu);
+        return;
+      }
+      const state = surfaceMap.get(menu);
+      if (!state) return;
+      applyPresentation(menu, state);
+      positionSurface(menu);
+    },
+    { signal: controller.signal },
+  );
+
+  menu.addEventListener(
+    EVENTS.hide,
+    (e) => {
+      if (!menu.hidden) closeSurface(menu, { restoreFocus: e.detail?.type === "escape" });
+    },
+    { signal: controller.signal },
+  );
+
+  menu.addEventListener(
+    EVENTS.outOfView,
+    () => {
+      if (!menu.hidden) closeSurface(menu);
+    },
+    { signal: controller.signal },
+  );
+
+  menu.addEventListener(
+    "keydown",
+    (e) => onMenuKeydown(e, { close: (target) => closeSurface(target) }),
+    { signal: controller.signal },
+  );
+
+  menu.addEventListener(
+    "click",
+    (e) => {
+      const state = surfaceMap.get(menu);
+      const disabledItem = e.target.closest?.(":disabled, [aria-disabled='true']");
+      if (disabledItem && menu.contains(disabledItem)) {
+        e.preventDefault();
+        return;
+      }
+      if (!state || state.autoClose === "outside" || state.autoClose === "false") return;
+      if (hasMenuItem(e.target)) closeSurface(menu);
+    },
+    { signal: controller.signal },
+  );
+
+  surfaceMap.set(menu, state);
+  return state;
+}
+
+export function isSurfaceOpen(menu) {
+  return menu.classList.contains(CLASSES.open) && !menu.hidden;
+}
+
+export function prepareSurface(menu) {
+  if (!menu) return;
+  menu.style.position = "fixed";
+  menu.hidden = true;
+  syncExpanded(menu, false);
+}
+
+export function openSurface(menu, opts = {}) {
+  if (!menu?.isConnected) return false;
+  if (isSurfaceOpen(menu)) return false;
+
+  const beforeOpen = new CustomEvent(EVENTS.surfaceOpen, {
+    bubbles: true,
+    cancelable: true,
+    detail: { surface: menu, options: opts },
+  });
+  if (!menu.dispatchEvent(beforeOpen)) return false;
+
+  for (const other of openSurfaces) {
+    if (other !== menu) closeSurface(other);
+  }
+
+  const anchor = opts.trigger || opts.source || null;
+  mountSurface(menu, anchor);
+  prepareSurface(menu);
+  const state = ensureSurfaceWired(menu);
+  state.trigger = opts.trigger || null;
+  state.source = opts.source || null;
+  state.point =
+    Number.isFinite(opts.x) && Number.isFinite(opts.y) ? { x: opts.x, y: opts.y } : null;
+  state.mobile = getMobileMode(menu, opts.mobile);
+  state.autoClose = getAutoCloseMode(menu, opts.autoClose);
+  state.placement = getPlacement(menu, opts.placement);
+  state.distance = getDistance(menu, opts.distance);
+  state.flip = opts.flip !== false;
+  state.shift = opts.shift !== false;
+  state.shiftPadding = opts.shiftPadding ?? 4;
+  state.scope = opts.scope;
+  state.restoreFocusTo = opts.restoreFocusTo || opts.trigger || opts.source || null;
+  state.closeId++;
+
+  menu.classList.add(CLASSES.open);
+  menu.hidden = false;
+  openSurfaces.add(menu);
+  applyPresentation(menu, state);
+  syncExpanded(menu, true);
+  positionSurface(menu);
+  return true;
+}
+
+export function closeSurface(menu, opts = {}) {
+  if (!menu || !isSurfaceOpen(menu)) return;
+
+  const state = surfaceMap.get(menu);
+  const closeId = state ? ++state.closeId : 0;
+  const wasSheet = state?.isSheet === true;
+  const activeElement = menu.ownerDocument.activeElement;
+  const shouldRestoreFocus = opts.restoreFocus ?? menu.contains(activeElement);
+  menu.classList.remove(CLASSES.open);
+  if (!wasSheet) {
+    menu.classList.remove(CLASSES.sheet);
+  }
+  menu.hidden = true;
+  const backdrop = state?.backdrop || null;
+  if (backdrop) backdrop.hidden = true;
+  openSurfaces.delete(menu);
+  syncExpanded(menu, false);
+
+  if (shouldRestoreFocus && state?.restoreFocusTo?.isConnected) {
+    state.restoreFocusTo.focus({ preventScroll: true });
+  }
+
+  waitForAnimations(menu, backdrop).then(() => {
+    if (!state || state.closeId !== closeId) return;
+    state.isSheet = false;
+    menu.classList.remove(CLASSES.sheet);
+    backdrop?.remove();
+    if (state.backdrop === backdrop) state.backdrop = null;
+    restoreSurface(menu);
+  });
+}
+
+export function disconnectSurface(menu) {
+  if (!menu) return;
+  closeSurface(menu);
+  const state = surfaceMap.get(menu);
+  if (state) {
+    state.backdrop?.remove();
+    state.untrack();
+    state.controller.abort();
+    surfaceMap.delete(menu);
+  }
+  restoreSurface(menu);
+}
+
+// Global outside-click listener runs at import time; keep SSR imports inert.
+if (typeof document !== "undefined") {
+  document.addEventListener("click", (e) => {
+    for (const menu of openSurfaces) {
+      const state = surfaceMap.get(menu);
+      if (!state || state.autoClose === "inside" || state.autoClose === "false") continue;
+      if (menu.contains(e.target) || state?.trigger?.contains(e.target)) continue;
+      closeSurface(menu);
+    }
+  });
+}