actual-css 0.1.0

package/src/js/flyout.js

@@ -0,0 +1,187 @@
+/*
+ * Flyout trigger — trigger adapter over the shared action-surface runtime.
+ *
+ * App menus keep roving focus and menuitem activation. Nav panels reuse the
+ * same surface lifecycle without menu semantics.
+ */
+
+import enhance from "./enhance.js";
+import { focusFirstDescendant } from "./focus.js";
+import { focusFirstMenuItem, focusLastMenuItem, getMenuItems } from "./menu.js";
+import { CLASSES } from "./selectors.js";
+import {
+  closeSurface,
+  disconnectSurface,
+  isSurfaceOpen,
+  openSurface,
+  prepareSurface,
+} from "./surface.js";
+
+// trigger -> { flyout, controller }
+const triggerMap = new WeakMap();
+const FLYOUT_SELECTOR = `.${CLASSES.flyout}`;
+const FLYOUT_TRIGGER_SELECTOR = "[aria-controls][aria-expanded]";
+
+function openFlyout(flyout, trigger) {
+  openSurface(flyout, { trigger, source: trigger });
+}
+
+function flyoutFor(trigger) {
+  const flyoutId = trigger.getAttribute("aria-controls");
+  const flyout = flyoutId && trigger.ownerDocument.getElementById(flyoutId);
+  return flyout?.matches(FLYOUT_SELECTOR) ? flyout : null;
+}
+
+function isMenuFlyout(flyout) {
+  return flyout.matches("menu");
+}
+
+function resolveCurrentFlyout(trigger, state) {
+  if (state.flyout?.isConnected) return state.flyout;
+
+  const flyout = flyoutFor(trigger);
+  if (!flyout) return null;
+
+  state.flyout = flyout;
+  prepareSurface(flyout);
+  if (!trigger.hasAttribute("aria-haspopup") && isMenuFlyout(flyout)) {
+    trigger.setAttribute("aria-haspopup", "menu");
+  }
+  return flyout;
+}
+
+function openAndFocusPanel(flyout, trigger) {
+  if (!isSurfaceOpen(flyout)) openFlyout(flyout, trigger);
+  focusFirstDescendant(flyout);
+}
+
+function onTriggerClick(e) {
+  const trigger = e.currentTarget;
+  const state = triggerMap.get(trigger);
+  if (!state) return;
+  e.stopPropagation();
+  const flyout = resolveCurrentFlyout(trigger, state);
+  if (!flyout) return;
+  if (isSurfaceOpen(flyout)) closeSurface(flyout);
+  else openFlyout(flyout, trigger);
+}
+
+function onTriggerKeydown(e) {
+  const trigger = e.currentTarget;
+  const state = triggerMap.get(trigger);
+  if (!state) return;
+  const flyout = resolveCurrentFlyout(trigger, state);
+  if (!flyout) return;
+  const items = getMenuItems(flyout);
+  const isActionList = items.length > 0;
+
+  if (!isActionList) {
+    switch (e.key) {
+      case "ArrowDown":
+        e.preventDefault();
+        openAndFocusPanel(flyout, trigger);
+        break;
+      case "Enter":
+      case " ":
+        e.preventDefault();
+        if (isSurfaceOpen(flyout)) closeSurface(flyout);
+        else openAndFocusPanel(flyout, trigger);
+        break;
+      case "Tab":
+        if (isSurfaceOpen(flyout) && !e.shiftKey && focusFirstDescendant(flyout)) {
+          e.preventDefault();
+        }
+        break;
+    }
+    return;
+  }
+
+  switch (e.key) {
+    case "ArrowDown":
+      e.preventDefault();
+      if (!isSurfaceOpen(flyout)) openFlyout(flyout, trigger);
+      focusFirstMenuItem(flyout);
+      break;
+    case "ArrowUp":
+      e.preventDefault();
+      if (!isSurfaceOpen(flyout)) openFlyout(flyout, trigger);
+      focusLastMenuItem(flyout);
+      break;
+    case "Home":
+      e.preventDefault();
+      if (!isSurfaceOpen(flyout)) openFlyout(flyout, trigger);
+      focusFirstMenuItem(flyout);
+      break;
+    case "End":
+      e.preventDefault();
+      if (!isSurfaceOpen(flyout)) openFlyout(flyout, trigger);
+      focusLastMenuItem(flyout);
+      break;
+    case "Enter":
+    case " ":
+      e.preventDefault();
+      if (!isSurfaceOpen(flyout)) {
+        openFlyout(flyout, trigger);
+        focusFirstMenuItem(flyout);
+      } else {
+        closeSurface(flyout);
+      }
+      break;
+    case "Tab":
+      if (isSurfaceOpen(flyout)) closeSurface(flyout);
+      break;
+  }
+}
+
+function connectTrigger(trigger) {
+  if (triggerMap.has(trigger)) return;
+  const flyout = flyoutFor(trigger);
+  if (!flyout) return;
+
+  const controller = new AbortController();
+  triggerMap.set(trigger, { flyout, controller });
+
+  prepareSurface(flyout);
+  if (!trigger.hasAttribute("aria-expanded")) {
+    trigger.setAttribute("aria-expanded", "false");
+  }
+  if (!trigger.hasAttribute("aria-haspopup") && isMenuFlyout(flyout)) {
+    trigger.setAttribute("aria-haspopup", "menu");
+  }
+
+  trigger.addEventListener("click", onTriggerClick, { signal: controller.signal });
+  trigger.addEventListener("keydown", onTriggerKeydown, { signal: controller.signal });
+}
+
+function disconnectTrigger(trigger) {
+  const state = triggerMap.get(trigger);
+  if (!state) return;
+  state.controller.abort();
+  triggerMap.delete(trigger);
+}
+
+function connectFlyout(flyout) {
+  if (!flyout.id) return;
+  const triggers = flyout.ownerDocument.querySelectorAll(
+    `${FLYOUT_TRIGGER_SELECTOR}[aria-controls="${CSS.escape(flyout.id)}"]`,
+  );
+  for (const trigger of triggers) {
+    if (!triggerMap.has(trigger)) connectTrigger(trigger);
+  }
+}
+
+function disconnectFlyout(flyout) {
+  if (!flyout) return;
+  disconnectSurface(flyout);
+}
+
+enhance({
+  [FLYOUT_TRIGGER_SELECTOR]: (trigger) => {
+    connectTrigger(trigger);
+    return () => disconnectTrigger(trigger);
+  },
+  [FLYOUT_SELECTOR]: (flyout) => {
+    connectFlyout(flyout);
+    return () => disconnectFlyout(flyout);
+  },
+});

package/src/js/focus.js

@@ -0,0 +1,35 @@
+const FOCUSABLE_SELECTOR = [
+  "a[href]",
+  "button",
+  "input",
+  "select",
+  "textarea",
+  "summary",
+  "[contenteditable]:not([contenteditable='false'])",
+  "[tabindex]",
+].join(",");
+
+export function isElementVisible(el) {
+  if (!el || el.hidden) return false;
+  if (typeof el.checkVisibility === "function") return el.checkVisibility();
+  return el.getClientRects().length > 0;
+}
+
+function isFocusable(el) {
+  return (
+    el.tabIndex >= 0 &&
+    !el.matches(":disabled") &&
+    isElementVisible(el) &&
+    !el.closest('[inert], [aria-hidden="true"]')
+  );
+}
+
+export function getFocusable(root) {
+  return [...root.querySelectorAll(FOCUSABLE_SELECTOR)].filter(isFocusable);
+}
+
+export function focusFirstDescendant(root) {
+  const target = getFocusable(root)[0];
+  target?.focus();
+  return !!target;
+}

package/src/js/index.js

@@ -0,0 +1,26 @@
+/*
+ * Actual CSS - JavaScript runtime.
+ *
+ * Each module self-registers via observer: importing the default runtime
+ * enables common behaviors. No DOMContentLoaded ceremony, no init calls.
+ * Injected content wires automatically; removal cleans up automatically.
+ *
+ * A plain `<script src="actual.js"></script>` (no bundler, no import) still
+ * gets the full runtime, including declarative triggers like status's
+ * `command="--status"` and the `actual:status` event — no global needed to
+ * drive them from other inline scripts either.
+ */
+
+import "./flyout.js";
+import "./context-menu.js";
+import "./dialog.js";
+// Legacy <dialog> shim for browsers below Baseline 2023; omit in custom builds.
+import "./dialog-fallback.js";
+import "./tab.js";
+import "./tooltip.js";
+import "./scrollspy.js";
+import "./filter.js";
+import "./mask.js";
+import "./password.js";
+import "./validation.js";
+import "./status.js";

package/src/js/input.js

@@ -0,0 +1,47 @@
+/*
+ * Input helpers shared by text-entry enhancers.
+ */
+
+export function selectionStart(el) {
+  return typeof el.selectionStart === "number" ? el.selectionStart : el.value.length;
+}
+
+export function setCaret(el, position) {
+  if (document.activeElement !== el) return;
+  if (typeof el.setSelectionRange !== "function") return;
+  try {
+    el.setSelectionRange(position, position);
+  } catch {
+    // Some input types do not support text selection.
+  }
+}
+
+export function dispatchInput(el) {
+  el.dispatchEvent(new Event("input", { bubbles: true }));
+}
+
+export function onTextInput(el, handler, signal) {
+  let composing = false;
+
+  function run(event) {
+    if (composing || event.isComposing) return;
+    handler(event);
+  }
+
+  el.addEventListener(
+    "compositionstart",
+    () => {
+      composing = true;
+    },
+    { signal },
+  );
+  el.addEventListener(
+    "compositionend",
+    (event) => {
+      composing = false;
+      run(event);
+    },
+    { signal },
+  );
+  el.addEventListener("input", run, { signal });
+}

package/src/js/keys.js

@@ -0,0 +1,30 @@
+/*
+ * Keyboard helpers for small roving-focus widgets.
+ *
+ * Components still own key dispatch and side effects. These helpers only
+ * centralize item lookup, edge handling, and optional wrapping.
+ */
+
+export function firstItem(items) {
+  return items[0] || null;
+}
+
+export function lastItem(items) {
+  return items[items.length - 1] || null;
+}
+
+export function nextItem(items, current, delta, opts = {}) {
+  if (!items.length) return null;
+
+  const wrap = opts.wrap !== false;
+  const idx = items.indexOf(current);
+  if (idx === -1) {
+    return delta > 0 ? firstItem(items) : lastItem(items);
+  }
+
+  const next = idx + delta;
+  if (!wrap) return items[next] || null;
+
+  const wrapped = ((next % items.length) + items.length) % items.length;
+  return items[wrapped];
+}

package/src/js/mask.js

@@ -0,0 +1,184 @@
+/*
+ * Mask — token-based input masks for fixed-shape values.
+ *
+ * data-mask="999-aaa" applies a token mask.
+ */
+
+import enhance from "./enhance.js";
+import { dispatchInput, onTextInput, selectionStart, setCaret } from "./input.js";
+
+const SELECTOR = "input[data-mask]";
+const TOKEN_TESTS = {
+  9: (char) => /^\d$/u.test(char),
+  a: (char) => /^\p{L}$/u.test(char),
+  "*": () => true,
+};
+
+function isToken(char) {
+  return Object.hasOwn(TOKEN_TESTS, char);
+}
+
+function parseMaskValue(value, mask) {
+  const pattern = [...mask];
+  const raw = [];
+  const positions = [];
+  let maskIndex = 0;
+  let valueIndex = 0;
+
+  valueLoop: for (const char of value) {
+    valueIndex += char.length;
+
+    while (maskIndex < pattern.length) {
+      const part = pattern[maskIndex];
+
+      if (!isToken(part)) {
+        maskIndex++;
+        if (char === part) continue valueLoop;
+        continue;
+      }
+
+      if (TOKEN_TESTS[part](char)) {
+        raw.push(char);
+        positions.push(valueIndex);
+        maskIndex++;
+      }
+      continue valueLoop;
+    }
+
+    break;
+  }
+
+  return { positions, raw };
+}
+
+function rawMaskChars(value, mask) {
+  return parseMaskValue(value, mask).raw;
+}
+
+function appendFollowingLiterals(mask, start) {
+  let out = "";
+  for (let i = start; i < mask.length && !isToken(mask[i]); i++) {
+    out += mask[i];
+  }
+  return out;
+}
+
+function formatRaw(raw, mask, inputType = "") {
+  const autoLiteral = inputType.startsWith("insert");
+  let rawIndex = 0;
+  let out = "";
+
+  for (let i = 0; i < mask.length; i++) {
+    const token = mask[i];
+
+    if (!isToken(token)) {
+      if (rawIndex < raw.length) out += token;
+      continue;
+    }
+
+    let matched = false;
+    while (rawIndex < raw.length) {
+      const char = raw[rawIndex];
+      rawIndex++;
+      if (!TOKEN_TESTS[token](char)) continue;
+      out += char;
+      matched = true;
+      break;
+    }
+
+    if (!matched) break;
+
+    if (autoLiteral && rawIndex >= raw.length) {
+      out += appendFollowingLiterals(mask, i + 1);
+      break;
+    }
+  }
+
+  return out;
+}
+
+function applyMask(value, mask, inputType = "") {
+  if (!mask) return value;
+  return formatRaw(rawMaskChars(value, mask), mask, inputType);
+}
+
+function caretForMask(value, mask, rawCount) {
+  if (rawCount <= 0) return 0;
+
+  const position = parseMaskValue(value, mask).positions[rawCount - 1];
+  if (position == null) return value.length;
+
+  const pattern = [...mask];
+  let tokenCount = 0;
+  let patternIndex = 0;
+  for (; patternIndex < pattern.length; patternIndex++) {
+    if (!isToken(pattern[patternIndex])) continue;
+    tokenCount++;
+    if (tokenCount === rawCount) break;
+  }
+
+  let caret = position;
+  for (patternIndex++; patternIndex < pattern.length; patternIndex++) {
+    const literal = pattern[patternIndex];
+    if (isToken(literal) || !value.startsWith(literal, caret)) break;
+    caret += literal.length;
+  }
+  return caret;
+}
+
+function connectMask(el) {
+  const mask = el.dataset.mask || "";
+  if (!mask) return;
+  const controller = new AbortController();
+  let masking = false;
+  // Last value this handler produced/saw. Distinguishes "backspaced only a
+  // literal" (delete the raw character before it) from a selection deletion
+  // that removed raw characters (just reformat, literals may come back).
+  let lastValue = el.value;
+
+  onTextInput(
+    el,
+    (event) => {
+      if (masking) return;
+
+      const inputType = event.inputType || "";
+      const caret = selectionStart(el);
+      let rawBeforeCaret = rawMaskChars(el.value.slice(0, caret), mask).length;
+      const previous = el.value;
+      let next = applyMask(previous, mask, inputType);
+      const onlyLiteralsRemoved =
+        rawMaskChars(previous, mask).length === rawMaskChars(lastValue, mask).length;
+
+      if (inputType.startsWith("delete") && onlyLiteralsRemoved && next.length > previous.length) {
+        const raw = rawMaskChars(previous, mask);
+        const deleteIndex =
+          inputType === "deleteContentForward" ? rawBeforeCaret : rawBeforeCaret - 1;
+
+        if (deleteIndex >= 0 && deleteIndex < raw.length) {
+          raw.splice(deleteIndex, 1);
+          rawBeforeCaret = Math.max(0, deleteIndex);
+          next = formatRaw(raw, mask, inputType);
+        }
+      }
+
+      lastValue = next;
+      if (next === previous) return;
+
+      el.value = next;
+      setCaret(el, caretForMask(next, mask, rawBeforeCaret));
+      try {
+        masking = true;
+        dispatchInput(el);
+      } finally {
+        masking = false;
+      }
+    },
+    controller.signal,
+  );
+
+  return () => controller.abort();
+}
+
+enhance({
+  [SELECTOR]: connectMask,
+});

package/src/js/menu.js

@@ -0,0 +1,88 @@
+import { isElementVisible } from "./focus.js";
+import { firstItem, lastItem, nextItem } from "./keys.js";
+
+const MENU_ITEM_TARGET_SELECTORS = ["button", "a", '[role="menuitem"]'];
+// Item contract, mirrored from flyout.css: a button, link, or menuitem
+// directly in the flyout or directly in any of its <li>. Prefixed with
+// .flyout rather than :scope because hasMenuItem() matches it via closest(),
+// where :scope would resolve to the target element instead of the flyout.
+export const MENU_ITEM_SELECTOR = MENU_ITEM_TARGET_SELECTORS.flatMap((target) => [
+  `.flyout > ${target}`,
+  `.flyout li > ${target}`,
+]).join(",");
+
+function isUsableMenuItem(item) {
+  return (
+    !item.disabled &&
+    item.getAttribute("aria-disabled") !== "true" &&
+    isElementVisible(item) &&
+    !item.closest("[hidden], [inert], [aria-hidden='true']")
+  );
+}
+
+export function getMenuItems(menu) {
+  return [...menu.querySelectorAll(MENU_ITEM_SELECTOR)].filter(isUsableMenuItem);
+}
+
+function isAriaMenuItem(item) {
+  return item.getAttribute("role") === "menuitem";
+}
+
+function activateCurrentItem(menu) {
+  const item = document.activeElement;
+  if (!menu.contains(item) || !isAriaMenuItem(item)) return false;
+
+  item.click();
+  return true;
+}
+
+export function hasMenuItems(menu) {
+  return getMenuItems(menu).length > 0;
+}
+
+export function hasMenuItem(target) {
+  return !!target.closest?.(MENU_ITEM_SELECTOR);
+}
+
+export function focusFirstMenuItem(menu) {
+  firstItem(getMenuItems(menu))?.focus();
+}
+
+export function focusLastMenuItem(menu) {
+  lastItem(getMenuItems(menu))?.focus();
+}
+
+export function onMenuKeydown(e, { close }) {
+  const menu = e.currentTarget;
+  const items = getMenuItems(menu);
+  if (!items.length) return;
+
+  switch (e.key) {
+    case "ArrowDown":
+      e.preventDefault();
+      nextItem(items, document.activeElement, 1, { wrap: true })?.focus();
+      break;
+    case "ArrowUp":
+      e.preventDefault();
+      nextItem(items, document.activeElement, -1, { wrap: true })?.focus();
+      break;
+    case "Home":
+      e.preventDefault();
+      firstItem(items)?.focus();
+      break;
+    case "End":
+      e.preventDefault();
+      lastItem(items)?.focus();
+      break;
+    case "Tab":
+      close(menu);
+      break;
+    case "Enter":
+    case " ":
+      if (activateCurrentItem(menu)) {
+        e.preventDefault();
+        close(menu);
+      }
+      break;
+  }
+}

package/src/js/password.js

@@ -0,0 +1,98 @@
+/*
+ * Password — show/hide toggle for password inputs.
+ *
+ * Declarative, through the command invoker pattern:
+ *
+ *   <div class="join">
+ *     <input class="input" type="password" id="pw" autocomplete="current-password">
+ *     <button class="btn outline" type="button" commandfor="pw"
+ *             command="--password-toggle" aria-controls="pw"
+ *             aria-label="Show password" aria-pressed="false"></button>
+ *   </div>
+ *
+ * The module flips the input between type="password" and type="text" and
+ * mirrors the state on every linked trigger through aria-pressed (styled by
+ * .btn[aria-pressed="true"]). Keep the trigger label stable — aria-pressed
+ * already announces the state, so a label that flips to "Hide" reads as a
+ * double negation to screen readers.
+ *
+ * A revealed value does not survive navigation: a non-canceled form submit and
+ * pagehide (bfcache) both revert the input to type="password", so returning to
+ * the page cannot land on a readable password. A canceled submit (validation,
+ * ajax) keeps the value revealed — nothing navigated away.
+ */
+import { commandSelector, registerCommands, targetFor } from "./command.js";
+
+const PASSWORD_COMMANDS = ["--password-toggle"];
+const TRIGGER_SELECTOR = commandSelector(PASSWORD_COMMANDS);
+
+// Inputs currently revealed by this module — the only ones ever reverted.
+// This set is intentionally iterable so pagehide also covers closed shadow
+// roots. Entries leave the set as soon as their input is masked again.
+const revealed = new Set();
+const submitRoots = new WeakSet();
+
+function resolvePasswordInput(trigger) {
+  const target = targetFor(trigger);
+  const isPassword =
+    target?.localName === "input" && (target.type === "password" || revealed.has(target));
+  return isPassword ? target : null;
+}
+
+function linkedTriggers(input) {
+  if (!input.id) return [];
+  return input
+    .getRootNode()
+    .querySelectorAll(`${TRIGGER_SELECTOR}[commandfor="${CSS.escape(input.id)}"]`);
+}
+
+function setRevealed(input, reveal) {
+  input.type = reveal ? "text" : "password";
+  if (reveal) {
+    revealed.add(input);
+  } else {
+    revealed.delete(input);
+  }
+  for (const trigger of linkedTriggers(input)) {
+    trigger.setAttribute("aria-pressed", String(reveal));
+  }
+}
+
+function handleSubmit(event) {
+  if (event.defaultPrevented) return;
+  for (const element of event.target.elements ?? []) {
+    if (revealed.has(element)) setRevealed(element, false);
+  }
+}
+
+function watchSubmitRoot(input) {
+  const root = input.getRootNode();
+  if (submitRoots.has(root)) return;
+  submitRoots.add(root);
+  root.addEventListener("submit", handleSubmit);
+}
+
+registerCommands(PASSWORD_COMMANDS, {
+  resolve: resolvePasswordInput,
+  prepare: (trigger, input) => {
+    trigger.setAttribute("aria-controls", input.id);
+    if (!trigger.hasAttribute("aria-pressed")) {
+      trigger.setAttribute("aria-pressed", "false");
+    }
+  },
+  handle: (event, _trigger, input) => {
+    event.preventDefault();
+    const reveal = input.type === "password";
+    if (reveal) watchSubmitRoot(input);
+    setRevealed(input, reveal);
+  },
+});
+
+if (typeof document !== "undefined") {
+  submitRoots.add(document);
+  document.addEventListener("submit", handleSubmit);
+
+  window.addEventListener("pagehide", () => {
+    for (const input of revealed) setRevealed(input, false);
+  });
+}