meta-sovereign 0.49.13 → 0.49.14

package/js/src/web/app.css

@@ -12622,7 +12622,12 @@ audio.remote-player {
 :root[data-effects='reduced'] *::after {
   animation-duration: 0.01ms !important;
   animation-iteration-count: 1 !important;
-  transition-duration: 0.01ms !important;
+  /* 0s, not 0.01ms: the default transition-property is `all`, so any
+     non-zero duration turns every colour change (the theme switch at
+     load) into a transition, and axe read light text on a dark fill
+     (R-Z22). */
+  transition-duration: 0s !important;
+  transition-delay: 0s !important;
 }
 :root[data-effects='reduced'] {
   --surface-glass-bg: var(--bg-elev);
@@ -12637,3 +12642,10 @@ audio.remote-player {
     0 0 0 4px rgba(0, 0, 0, 0.5),
     0 0 0 3px rgba(102, 178, 255, 1);
 }
+
+/* The card collapses to its title and buttons when its target cannot be
+   scrolled clear of it (R-Z22). */
+.tutorial-overlay .tutorial-step[data-compact='true'] .tutorial-body,
+.tutorial-overlay .tutorial-step[data-compact='true'] .tutorial-examples {
+  display: none;
+}

package/js/src/web/tutorial-clear.js

@@ -0,0 +1,151 @@
+// The card never covers the control it asks the user to click (R-Z22).
+//
+// A card docked to the screen edge (a section too big for a side, a
+// short or narrow screen, taller fonts than the developer's) can end
+// up over its own target: the target was scrolled "into view" before
+// the card's size was known. Once the card is placed, this checks the
+// two boxes and, if they meet, scrolls the target into the band the
+// card leaves free (`scroll-margin` on the target, so every clipping
+// container — the page, a drawer — takes part). If the target cannot
+// be moved clear (the band is smaller than the target and the page
+// cannot scroll further) the card collapses to its title and buttons,
+// which is the smaller dock.
+
+import { useEffect, useState } from 'react';
+import { GAP, intersects } from './tutorial-placement.js';
+
+const ATTEMPT_DELAYS_MS = [0, 250, 700];
+const RESIZE_DEBOUNCE_MS = 60;
+
+const boxOf = (node) => {
+  const r = node.getBoundingClientRect();
+  return { top: r.top, left: r.left, width: r.width, height: r.height };
+};
+
+/**
+ * Where the card leaves room: `{top, bottom, below}` in screen
+ * coordinates. A card in the lower half leaves the space above it.
+ */
+export const freeBand = (card, viewport, chromeBottom = 0) => {
+  const below = card.top + card.height / 2 > viewport.height / 2;
+  return below
+    ? { top: chromeBottom, bottom: card.top - GAP, below }
+    : { top: card.top + card.height + GAP, bottom: viewport.height, below };
+};
+
+/**
+ * Is the target where the card leaves it? A target that fits the free
+ * band must not meet the card at all. One taller than the band (the
+ * services grid) runs under the card by nature: it is read from its
+ * top, so that top must sit in the upper part of the band, with the
+ * first controls (sign-ins, the first services) in the clear.
+ */
+export const placedClear = (target, card, band, viewport) => {
+  if (!intersects(card, target)) {
+    return true;
+  }
+  // Too tall for the screen even without a card: read from the top.
+  if (target.height <= viewport.height - band.top - GAP) {
+    return false;
+  }
+  const size = band.bottom - band.top;
+  return target.top >= band.top - 2 && target.top <= band.top + size / 4;
+};
+
+const scrollInto = (element, band, viewport, block) => {
+  const style = element.style;
+  const saved = [style.scrollMarginTop, style.scrollMarginBottom];
+  style.scrollMarginTop = `${Math.max(0, band.top)}px`;
+  style.scrollMarginBottom = `${Math.max(0, viewport.height - band.bottom)}px`;
+  try {
+    element.scrollIntoView?.({ block, inline: 'nearest', behavior: 'auto' });
+  } finally {
+    [style.scrollMarginTop, style.scrollMarginBottom] = saved;
+  }
+};
+
+/**
+ * One check: 'clear' when the target (and the control the step names
+ * inside it, `mustShow`) is where the card leaves it, else it scrolls
+ * and reports 'scrolled', or 'stuck' (nothing more to scroll).
+ */
+export const clearOnce = (element, cardNode, viewport, mustShow = '') => {
+  const chrome = document.querySelector('.topbar')?.getBoundingClientRect();
+  const band = freeBand(boxOf(cardNode), viewport, chrome?.bottom ?? 0);
+  const control = mustShow ? element.querySelector(mustShow) : null;
+  const ok = () => {
+    const card = boxOf(cardNode);
+    const covered = control && intersects(card, boxOf(control));
+    return placedClear(boxOf(element), card, band, viewport) && !covered;
+  };
+  if (ok()) {
+    return 'clear';
+  }
+  const target = boxOf(element);
+  const fits = target.height <= band.bottom - band.top;
+  scrollInto(element, band, viewport, fits ? 'nearest' : 'start');
+  if (control && !ok()) {
+    scrollInto(control, band, viewport, 'nearest');
+  }
+  return ok() ? 'scrolled' : 'stuck';
+};
+
+/**
+ * Keeps the target clear of the card after every placement. Returns
+ * true when the card had to collapse (title and buttons only).
+ */
+export const useClearOfCard = ({
+  cardRef,
+  element,
+  stepId,
+  placed,
+  cardSize,
+  viewportOf,
+  mustShow = '',
+}) => {
+  const [collapsed, setCollapsed] = useState(null);
+  const compact = collapsed === stepId;
+  const key = `${placed?.side}|${placed?.style?.top}|${placed?.style?.left}`;
+  useEffect(() => {
+    const node = cardRef.current;
+    if (
+      !element?.isConnected ||
+      !node ||
+      !placed ||
+      placed.side === 'pending'
+    ) {
+      return undefined;
+    }
+    const check = (final) => {
+      const result =
+        element.isConnected && node.isConnected
+          ? clearOnce(element, node, viewportOf(), mustShow)
+          : 'clear';
+      if (result === 'stuck' && final) {
+        setCollapsed(stepId);
+      }
+    };
+    const timers = ATTEMPT_DELAYS_MS.map((delay, i) =>
+      globalThis.setTimeout(() => {
+        check(i === ATTEMPT_DELAYS_MS.length - 1);
+      }, delay)
+    );
+    // The target can change size after the card is placed (a panel
+    // that finishes loading, a tab with less in it): check again.
+    let late = 0;
+    const Observer = globalThis.ResizeObserver;
+    const observer = Observer
+      ? new Observer(() => {
+          globalThis.clearTimeout(late);
+          late = globalThis.setTimeout(() => check(true), RESIZE_DEBOUNCE_MS);
+        })
+      : null;
+    observer?.observe(element);
+    return () => {
+      timers.forEach((timer) => globalThis.clearTimeout(timer));
+      globalThis.clearTimeout(late);
+      observer?.disconnect();
+    };
+  }, [stepId, element, key, cardSize?.height, compact]);
+  return compact;
+};

package/js/src/web/tutorial.js

@@ -38,6 +38,7 @@ import {
 } from './tutorial-follow.js';
 import { parseConnectionHash } from './connections/hash.js';
 import { startIndex } from './tutorial-start.js';
+import { useClearOfCard } from './tutorial-clear.js';
 
 const el = React.createElement;
 
@@ -114,6 +115,8 @@ export const defaultSteps = [
     id: 'pick',
     connecting: true,
     tutorialId: 'connections:list',
+    // The first service stays clear of the card (R-Z22).
+    mustShow: '[data-tutorial-id="connections:email"]',
     route: { view: 'connections', detail: false },
     completeAt: { view: 'connections', detail: true },
     titleKey: 'tutorial.connections.title',
@@ -720,13 +723,19 @@ const prefersReducedMotion = () =>
 // of the screen — the card goes in that room, above it, never over it.
 const tooTall = (r, room) => r.height > (globalThis.innerHeight ?? 0) - room;
 
+// The sticky header's bottom edge: a tall target's top goes just below
+// it; useClearOfCard then makes room for the card (R-Z22).
+const chromeBottom = () =>
+  globalThis.document?.querySelector('.topbar')?.getBoundingClientRect()
+    .bottom ?? 0;
+
 const inView = (element, room) => {
   const r = element.getBoundingClientRect();
   const height = globalThis.innerHeight ?? 0;
   const width = globalThis.innerWidth ?? 0;
   const across = r.left >= 0 && r.right <= width;
   return tooTall(r, room)
-    ? across && r.top >= room - 1 && r.top <= Math.max(room, height / 2)
+    ? across && r.top >= chromeBottom() - 1 && r.top <= height / 2
     : across && r.top >= 0 && r.bottom <= height;
 };
 
@@ -766,7 +775,7 @@ const useRevealTarget = (stepId, element, room = 0) => {
         tries === 0 && !prefersReducedMotion() ? 'smooth' : 'auto';
       const r = element.getBoundingClientRect();
       if (tooTall(r, room)) {
-        globalThis.scrollBy?.({ top: r.top - room, behavior });
+        globalThis.scrollBy?.({ top: r.top - chromeBottom(), behavior });
       } else {
         element.scrollIntoView?.({
           block: 'nearest',
@@ -791,6 +800,8 @@ const useRevealTarget = (stepId, element, room = 0) => {
 // Focus follows the tour once the user is in it. When the tour opens
 // by itself on page load (nothing focused yet), the first step leaves
 // focus alone so the skip link stays the first Tab stop.
+const FOCUS_RETRY_MS = [120, 350, 800];
+
 const useDialogFocus = (cardRef, stepId, visible) => {
   const doc = globalThis.document;
   const opened = useRef(null);
@@ -807,10 +818,31 @@ const useDialogFocus = (cardRef, stepId, visible) => {
   );
   useEffect(() => {
     if (!visible || stepId === opened.current.quietStep) {
-      return;
+      return undefined;
     }
     opened.current.quietStep = null;
-    cardRef.current?.focus?.({ preventScroll: true });
+    const grab = () => cardRef.current?.focus?.({ preventScroll: true });
+    grab();
+    // The page may take focus back a moment later (a view that focuses
+    // its composer as it mounts, a renderer that was still painting):
+    // grab it again, for a short while, until the user acts (R-Z22).
+    let acted = false;
+    const onAct = () => {
+      acted = true;
+    };
+    const events = ['keydown', 'pointerdown', 'mousedown', 'touchstart'];
+    events.forEach((name) => doc?.addEventListener(name, onAct, true));
+    const timers = FOCUS_RETRY_MS.map((delay) =>
+      globalThis.setTimeout(() => {
+        if (!acted && doc?.activeElement !== cardRef.current) {
+          grab();
+        }
+      }, delay)
+    );
+    return () => {
+      timers.forEach((timer) => globalThis.clearTimeout(timer));
+      events.forEach((name) => doc?.removeEventListener(name, onAct, true));
+    };
   }, [stepId, visible]);
 };
 
@@ -871,6 +903,7 @@ const Step = ({
   side,
   follow,
   arrowStyle,
+  compact = false,
 }) => {
   const t = useT();
   const titleId = `tutorial-step-${step.id}`;
@@ -886,6 +919,7 @@ const Step = ({
       'data-tutorial-step': step.id,
       'data-side': side,
       'data-follow': follow,
+      'data-compact': compact ? 'true' : undefined,
       tabIndex: -1,
       style,
     },
@@ -1182,6 +1216,15 @@ const TutorialLayer = ({
   const layout = cardLayout({ placed, cardSize, waiting });
   useDialogFocus(cardRef, step.id, layout.side !== 'pending');
   useDockSpace(dockSpace(layout, cardSize));
+  const compact = useClearOfCard({
+    cardRef,
+    element,
+    stepId: step.id,
+    placed: layout,
+    cardSize,
+    viewportOf: viewportSize,
+    mustShow: step.mustShow,
+  });
   return el(
     'div',
     {
@@ -1212,6 +1255,7 @@ const TutorialLayer = ({
         side: layout.side,
         follow: layout.mode,
         arrowStyle: layout.arrowStyle,
+        compact,
       }),
     ]
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "meta-sovereign",
-  "version": "0.49.13",
+  "version": "0.49.14",
   "description": "Personal meta profile sovereign system - fully local, privacy-respecting personal CRM and unified messenger across services",
   "type": "module",
   "main": "js/src/index.js",