@celestia-island/hikari 0.4.4 → 0.30.0

package/src/components/HkModal.tsx

@@ -5,6 +5,7 @@ import {
   onBeforeUnmount,
   onMounted,
   ref,
+  shallowRef,
   Teleport,
   Transition,
   watch,
@@ -13,9 +14,16 @@ import {
 
 import { useI18n } from "../i18n/context";
 import "./HkModal.scss";
+import { focusFirst, trapFocus } from "../utils/dom";
 import { useOverlay } from "../runtime/useOverlay";
 import { usePopupManager } from "../runtime/usePopupManager";
+import { createBackGuard } from "../runtime/backStack";
+import { scheduleFrame, type AnimationHandle } from "../runtime/animationBus";
+import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "../composables/useOverlayScrollbar";
+import { useSurfaceTransition } from "../composables/useSurfaceTransition";
+import { useSizeMorph } from "../composables/useSizeMorph";
 import HButton from "./HkButton";
+import HFab from "./HkFab";
 import HSpinner from "./HkSpinner";
 
 export interface ModalAction {
@@ -29,28 +37,6 @@ export interface ModalAction {
 const FOCUSABLE_SELECTOR =
   'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
 
-function trapFocus(container: HTMLElement, e: KeyboardEvent): void {
-  const focusable = container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR);
-  if (focusable.length === 0) return;
-  const first = focusable[0];
-  const last = focusable[focusable.length - 1];
-  if (e.shiftKey) {
-    if (document.activeElement === first) {
-      e.preventDefault();
-      last.focus();
-    }
-  } else {
-    if (document.activeElement === last) {
-      e.preventDefault();
-      first.focus();
-    }
-  }
-}
-
-function focusFirst(container: HTMLElement): void {
-  const el = container.querySelector<HTMLElement>(FOCUSABLE_SELECTOR);
-  if (el) el.focus();
-}
 
 export default defineComponent({
   name: "HkModal",
@@ -66,6 +52,14 @@ export default defineComponent({
     windowed: { type: Boolean, default: false },
     overscanScreens: { type: Number, default: 1 },
     autoFollow: { type: Boolean, default: false },
+    /**
+     * Consume the browser/system back gesture while open (window-first
+     * back priority): a marked history entry is pushed on open so back
+     * closes the modal instead of leaving the page. Only meaningful
+     * together with `closable`; disable for surfaces that manage their
+     * own history entries.
+     */
+    backGuard: { type: Boolean, default: true },
   },
   emits: {
     "update:modelValue": (_value: boolean) => true,
@@ -74,11 +68,31 @@ export default defineComponent({
   setup(props, { emit, slots }) {
     const { t } = useI18n();
     const manager = usePopupManager();
-    const overlay = useOverlay({ name: "hk-modal" });
+    // Open/close motion reported into the unified animation context
+    // (animationBus) — scrim and content on separate tracks so each
+    // layer's report arms/cancels independently.
+    const surf = useSurfaceTransition(320);
+    const overlayHooks = surf.hooks("overlay");
+    const contentHooks = surf.hooks("content");
+    const overlay = useOverlay({
+      name: "hk-modal",
+      // A global closeAll() must be able to actually close this modal
+      // (not just untrack it) — route it through the same closable
+      // guard as the user-initiated paths.
+      onCloseRequested: () => { if (props.closable) close(); },
+    });
 
     const handle = ref<{ id: string; zIndex: number } | null>(null);
     const bodyRef = ref<HTMLElement>();
     const contentRef = ref<HTMLElement>();
+    /** Natural-height probe inside the scroll container: the body's
+     *  content wrapper, whose height is the content's intrinsic height
+     *  regardless of scroll — the size morph measures this (see
+     *  useSizeMorph). */
+    const innerRef = ref<HTMLElement>();
+    // Content-driven size morphing: the frame follows content growth with
+    // the height transition instead of snapping (see useSizeMorph).
+    const morph = useSizeMorph(contentRef, innerRef);
     const shouldRender = ref(false);
     let previouslyFocused: HTMLElement | null = null;
     let unmounted = false;
@@ -95,9 +109,35 @@ export default defineComponent({
     // Auto-follow state
     let autoFollowMutationObserver: MutationObserver | null = null;
     const isFollowing = ref(true);
-    let userScrolled = false;
+    /** Body actually scrolls (drives the "Auto" tag visibility). */
+    const hasOverflow = shallowRef(false);
+    /**
+     * Sticky user-intent flag. Set by wheel / touch / drag-press /
+     * scroll-key gestures and consumed by the scroll handler; cleared
+     * by every programmatic movement (which is never user intent).
+     * Fling momentum keeps firing scroll events without new touches,
+     * which is why the flag stays set until consumed or cleared.
+     */
+    let gestureDirty = false;
+    /** performance.now() of the last gesture that raised the flag —
+     *  drives the settle-frame quiet window below. */
+    let gestureAt = 0;
     const scrollContainerRef = ref<HTMLElement>();
 
+    /**
+     * Window-first back priority: while this modal is the topmost open
+     * window, the back gesture (mobile back button/gesture, desktop
+     * browser back) closes it instead of navigating the page. Disabled
+     * for non-closable modals — back must not be swallowed by a surface
+     * it cannot close.
+     */
+    const backGuardEnabled = () => props.closable && props.backGuard;
+    const backGuard = createBackGuard({
+      onBack: () => {
+        if (backGuardEnabled()) close();
+      },
+    });
+
     function close() {
       emit("update:modelValue", false);
     }
@@ -209,30 +249,145 @@ export default defineComponent({
     }
 
     // --- Auto-follow ---
+    //
+    // Follow policy: ONLY real user motion can cancel following.
+    // Streaming content is pinned with direct scrollTop assignments
+    // drained across a few animation frames (never smooth-scroll
+    // chains), and every programmatic movement clears the sticky
+    // gesture flag — so mid-flight scroll events cannot flip isFollowing
+    // back and forth (the old flicker).
+
+    const FOLLOW_THRESHOLD = 32;
+    const SETTLE_FRAMES = 4;
+    /** Pending pin frames yield to gestures younger than this. */
+    const GESTURE_QUIET_MS = 250;
+
+    let settleRemaining = 0;
+    let settleHandle: AnimationHandle | null = null;
+
+    function runSettleFrame() {
+      settleHandle = null;
+      // A cancelled follow must not be fought by pending pins: drained
+      // frames bail out immediately (resumeJumpLatest re-kicks). The
+      // reset above must stay first so kickSettle() never sees a stale,
+      // already-consumed handle — that would deadlock all future pins.
+      if (!isFollowing.value) {
+        settleRemaining = 0;
+        return;
+      }
+      if (gestureDirty && performance.now() - gestureAt < GESTURE_QUIET_MS) {
+        // A live gesture is in flight: yield this frame to it and let
+        // the scroll handler judge the resulting position. Stale flags
+        // older than the quiet window fall through and are consumed
+        // below — no stale-flag stall, no fight against the finger.
+        if (settleRemaining > 0) {
+          settleRemaining--;
+          settleHandle = scheduleFrame(runSettleFrame);
+        }
+        return;
+      }
+      gestureDirty = false;
+      pinToBottom();
+      updateOverflow();
+      if (settleRemaining > 0) {
+        settleRemaining--;
+        settleHandle = scheduleFrame(runSettleFrame);
+      }
+    }
 
-    function scrollToBottom(smooth = false) {
+    function kickSettle() {
+      // hasOverflow gates the "Auto" tag and the jump FAB. It is only
+      // recomputed inside settle frames and scroll events; with windowed
+      // lists the body can grow late (async chunks, virtualized mounts)
+      // without either firing — poll it alongside the settle drain so the
+      // affordances appear on the frame the overflow actually exists.
+      updateOverflow();
+      settleRemaining = SETTLE_FRAMES;
+      if (settleHandle) return;
+      settleHandle = scheduleFrame(runSettleFrame);
+    }
+
+    function cancelSettle() {
+      settleHandle?.disconnect();
+      settleHandle = null;
+      settleRemaining = 0;
+    }
+
+    /** Direct assignment — no smooth scrolling, no intermediate events. */
+    function pinToBottom() {
       const el = scrollContainerRef.value;
       if (!el) return;
-      el.scrollTo({
-        top: el.scrollHeight,
-        behavior: smooth ? "smooth" : "instant" as ScrollBehavior,
-      });
+      el.scrollTop = el.scrollHeight;
+    }
+
+    function updateOverflow() {
+      const el = scrollContainerRef.value;
+      if (!el) return;
+      hasOverflow.value = el.scrollHeight > el.clientHeight + 4;
     }
 
     function onBodyScroll() {
       if (!props.autoFollow) return;
       const el = scrollContainerRef.value;
       if (!el) return;
-      const threshold = 32;
+      updateOverflow();
       const distanceFromBottom =
         el.scrollHeight - el.scrollTop - el.clientHeight;
-      if (distanceFromBottom > threshold) {
-        userScrolled = true;
-        isFollowing.value = false;
-      } else {
-        userScrolled = false;
+      if (distanceFromBottom > FOLLOW_THRESHOLD) {
+        // Without a sticky gesture flag nothing cancels here — streaming
+        // pins no longer flash anything.
+        if (gestureDirty) {
+          gestureDirty = false;
+          isFollowing.value = false;
+        }
+      } else if (!isFollowing.value) {
+        // User returned near the bottom (or a pin landed): re-arm naturally.
+        gestureDirty = false;
         isFollowing.value = true;
       }
+      // Sub-threshold events while still following must NOT touch the
+      // flag: a slow upward drag emits many <32px scrolls, and eating
+      // the flag on any of them would make cancellation impossible.
+    }
+
+    const GESTURE_KEYS = new Set([
+      "ArrowUp", "ArrowDown", "PageUp", "PageDown", "Home", "End", " ",
+    ]);
+
+    function markGesture() {
+      gestureDirty = true;
+      gestureAt = performance.now();
+    }
+
+    function onGestureKeydown(e: KeyboardEvent) {
+      if (GESTURE_KEYS.has(e.key)) {
+        gestureDirty = true;
+        gestureAt = performance.now();
+      }
+    }
+
+    /** Press-and-drag covers mouse/touch before the drag starts; the
+     *  flag stays sticky so post-fling momentum still cancels follow. */
+    function onGesturePointerdown(e: PointerEvent) {
+      if (e.button === 0) {
+        gestureDirty = true;
+        gestureAt = performance.now();
+      }
+    }
+
+    /** A press-drag longer than the quiet window would otherwise have
+     *  its flag purged mid-gesture (a mutation frame pins under the
+     *  finger and the rest of the drag can no longer cancel). Moving
+     *  while buttons are held re-stamps freshness; free hovering —
+     *  e.buttons === 0 — must NOT keep a stale flag alive forever. */
+    function onGesturePointermove(e: PointerEvent) {
+      if (e.buttons !== 0) markGesture();
+    }
+
+    /** Touch drags emit touchmove without pointermove on some engines
+     *  (and happy-dom tests synthesize either); belt and suspenders. */
+    function onGestureTouchmove() {
+      markGesture();
     }
 
     function setupAutoFollow() {
@@ -240,16 +395,24 @@ export default defineComponent({
       teardownAutoFollow();
 
       isFollowing.value = true;
-      userScrolled = false;
-      scrollToBottom(false);
+      gestureDirty = false;
+      pinToBottom();
+      updateOverflow();
+      kickSettle();
+
+      const el = scrollContainerRef.value!;
+      el.addEventListener("wheel", markGesture, { passive: true });
+      el.addEventListener("touchstart", markGesture, { passive: true });
+      el.addEventListener("touchmove", onGestureTouchmove, { passive: true });
+      el.addEventListener("keydown", onGestureKeydown);
+      el.addEventListener("pointerdown", onGesturePointerdown);
+      el.addEventListener("pointermove", onGesturePointermove, { passive: true });
 
       autoFollowMutationObserver = new MutationObserver(() => {
-        if (isFollowing.value && !unmounted) {
-          nextTick(() => scrollToBottom(true));
-        }
+        if (isFollowing.value && !unmounted) kickSettle();
       });
 
-      autoFollowMutationObserver.observe(scrollContainerRef.value, {
+      autoFollowMutationObserver.observe(el, {
         childList: true,
         subtree: true,
         characterData: true,
@@ -261,19 +424,53 @@ export default defineComponent({
         autoFollowMutationObserver.disconnect();
         autoFollowMutationObserver = null;
       }
+      const el = scrollContainerRef.value;
+      if (el) {
+        el.removeEventListener("wheel", markGesture);
+        el.removeEventListener("touchstart", markGesture);
+        el.removeEventListener("touchmove", onGestureTouchmove);
+        el.removeEventListener("keydown", onGestureKeydown);
+        el.removeEventListener("pointerdown", onGesturePointerdown);
+        el.removeEventListener("pointermove", onGesturePointermove);
+      }
+      cancelSettle();
       isFollowing.value = true;
-      userScrolled = false;
+      hasOverflow.value = false;
+      gestureDirty = false;
     }
 
-    function resumeAutoFollow() {
+    function resumeJumpLatest() {
       if (!props.autoFollow) return;
       isFollowing.value = true;
-      userScrolled = false;
-      scrollToBottom(true);
+      pinToBottom();
+      kickSettle();
     }
 
     // --- Lifecycle ---
 
+    // Overlay scrollbar on the scrolling body (shared chrome). The body
+    // mounts with the modal surface (shouldRender) and survives through
+    // the leave transition; attach after the DOM lands, detach on close
+    // and unmount so nothing leaks inside the Teleport portal.
+    let bodyScrollbar: OverlayScrollbarHandle | null = null;
+
+    function detachBodyScrollbar(): void {
+      bodyScrollbar?.detach();
+      bodyScrollbar = null;
+    }
+
+    watch(shouldRender, (render) => {
+      if (render) {
+        void nextTick(() => {
+          if (!shouldRender.value || !scrollContainerRef.value) return;
+          detachBodyScrollbar();
+          bodyScrollbar = attachOverlayScrollbars(scrollContainerRef.value, { axis: "vertical" });
+        });
+      } else {
+        detachBodyScrollbar();
+      }
+    });
+
     watch(
       () => props.modelValue,
       (val) => {
@@ -284,17 +481,36 @@ export default defineComponent({
             manager.unregister(handle.value.id);
           }
           shouldRender.value = true;
+          // Windows always block, so the kind alone lists this layer in
+          // the modal-stack breadcrumb on every form factor.
           handle.value = manager.register("modal", true, props.title);
           overlay.open();
+          if (backGuardEnabled() && backGuard.entries === 0) {
+            backGuard.push();
+          }
         } else {
           // Close happens via Transition onAfterLeave,
           // but if modelValue flips to false without Transition
           // (e.g. immediate), clean up now.
+          overlay.close();
+          backGuard.release();
         }
       },
       { immediate: true },
     );
 
+    // closable/backGuard may flip while open (submit flows disable
+    // closing): keep the owned entry in lockstep so back is never a
+    // dead gesture on a surface it can no longer close.
+    watch(
+      backGuardEnabled,
+      (enabled) => {
+        if (unmounted || !props.modelValue) return;
+        if (enabled && backGuard.entries === 0) backGuard.push();
+        else if (!enabled && backGuard.entries > 0) backGuard.release();
+      },
+    );
+
     watch(
       () => props.title,
       (newTitle) => {
@@ -310,8 +526,10 @@ export default defineComponent({
 
     onBeforeUnmount(() => {
       unmounted = true;
+      detachBodyScrollbar();
       teardownWindowed();
       teardownAutoFollow();
+      backGuard.destroy();
       if (handle.value) {
         manager.unregister(handle.value.id);
         handle.value = null;
@@ -358,7 +576,14 @@ export default defineComponent({
             style={{ zIndex: overlayZ.value }}
             onKeydown={onKeydown}
           >
-            <Transition name="hk-modal-overlay" appear>
+            <Transition
+              name="hk-modal-overlay"
+              appear
+              onBeforeEnter={overlayHooks.onBeforeEnter}
+              onAfterEnter={overlayHooks.onAfterEnter}
+              onBeforeLeave={overlayHooks.onBeforeLeave}
+              onAfterLeave={overlayHooks.onAfterLeave}
+            >
               {props.modelValue && (
                 <div
                   class="hk-modal-overlay"
@@ -369,8 +594,23 @@ export default defineComponent({
             <Transition
               name="hk-modal-content"
               appear
-              onAfterEnter={onAfterEnter}
-              onAfterLeave={onAfterLeave}
+              onBeforeEnter={contentHooks.onBeforeEnter}
+              onAfterEnter={() => {
+                contentHooks.onAfterEnter();
+                onAfterEnter();
+                // Size morphs arm once the open choreography finished —
+                // pinning during enter would override its height reveal.
+                morph.start();
+              }}
+              onBeforeLeave={() => {
+                contentHooks.onBeforeLeave();
+                // Release the pinned height so the leave owns the frame.
+                morph.stop();
+              }}
+              onAfterLeave={() => {
+                contentHooks.onAfterLeave();
+                onAfterLeave();
+              }}
             >
               {props.modelValue && (
                 <div
@@ -395,7 +635,7 @@ export default defineComponent({
                         {props.closable && (
                           <button
                             class="hk-modal-close"
-                            aria-label={t("hk.modal.close", "Close")}
+                            aria-label={t("hikari::modal.close", "Close")}
                             onClick={close}
                           >
                             <svg
@@ -424,30 +664,36 @@ export default defineComponent({
                       class="hk-modal-body-scroll"
                       onScroll={onBodyScroll}
                     >
-                      <div class="hk-modal-body-inner">
+                      <div ref={innerRef} class="hk-modal-body-inner">
                         {props.windowed
                           ? renderWindowedBody()
                           : slots.default?.()}
                       </div>
                     </div>
-                    {props.autoFollow && !isFollowing.value && (
-                      <div
-                        class="hk-modal-autofollow-bar"
-                        onClick={resumeAutoFollow}
-                      >
-                        <svg
-                          viewBox="0 0 24 24"
-                          fill="none"
-                          stroke="currentColor"
-                          stroke-width="2"
-                          stroke-linecap="round"
-                          width="14"
-                          height="14"
-                        >
-                          <polyline points="6 9 12 15 18 9" />
-                        </svg>
-                        <span>Auto</span>
-                      </div>
+                    {props.autoFollow && (
+                      <>
+                        {/* "Auto" marks ACTIVE follow: pinned at bottom
+                            with a body that overflows. Cancelled follow
+                            swaps it for the jump-back FAB instead. */}
+                        {hasOverflow.value && isFollowing.value && (
+                          <span
+                            class="hk-modal-autofollow-tag"
+                            aria-hidden="true"
+                          >
+                            {t("hikari::modal.auto", "Auto")}
+                          </span>
+                        )}
+                        {!isFollowing.value && (
+                          <HFab
+                            class="hk-modal-jump"
+                            positioning="absolute"
+                            corner="bottom-right"
+                            icon="ArrowDown"
+                            ariaLabel={t("hikari::modal.jumpToLatest", "Back to latest")}
+                            onClick={resumeJumpLatest}
+                          />
+                        )}
+                      </>
                     )}
                   </div>
                   {renderFooter()}

package/src/components/HkModalBreadcrumb.scss

@@ -2,7 +2,10 @@
   position: fixed;
   left: 50%;
   transform: translate(-50%, -50%);
-  z-index: var(--hk-breadcrumb-z, 100001);
+  /* Above every popup band's scrim (modal 1000+, dropdown 2000+; in-band
+     steps of 2 keep real stacks far below this) so multi-layer windows
+     never bury the strip; still below tooltip (3000) / toast (4000). */
+  z-index: var(--hk-breadcrumb-z, 2500);
   display: flex;
   align-items: center;
   gap: var(--hi-space-4, 0.5rem);

package/src/components/HkModalBreadcrumb.test.tsx

@@ -0,0 +1,111 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, nextTick } from "vue";
+
+import HkModalBreadcrumb from "./HkModalBreadcrumb";
+import { usePopupManager } from "../runtime/usePopupManager";
+
+const mounts: ReturnType<typeof createApp>[] = [];
+const containers: HTMLElement[] = [];
+// The registry is a module singleton shared with the strip.
+const manager = usePopupManager();
+
+afterEach(async () => {
+  for (const app of mounts.splice(0)) app.unmount();
+  for (const el of containers.splice(0)) el.remove();
+  for (const entry of [...manager.registry.value.values()]) {
+    manager.unregister(entry.id);
+  }
+  document.body.style.overflow = "";
+});
+
+async function mountStrip(): Promise<void> {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  containers.push(container);
+  const app = createApp(HkModalBreadcrumb);
+  mounts.push(app);
+  app.mount(container);
+  await nextTick();
+}
+
+function strip(): HTMLElement | null {
+  return document.querySelector("nav.hk-modal-breadcrumb");
+}
+
+function labels(): string[] {
+  const nav = strip();
+  if (!nav) return [];
+  return [...nav.querySelectorAll(".hk-modal-breadcrumb-item")].map(
+    (el) => el.textContent ?? "",
+  );
+}
+
+describe("HkModalBreadcrumb window-stack policy", () => {
+  it("treats an anchored desktop menu as a hidden level", async () => {
+    // Theme window + an untitled anchor-attached popover (blocking=false):
+    // the popover is not a window the user navigates, so a single-window
+    // situation stays strip-less.
+    manager.register("modal", true, "Custom theme");
+    manager.register("dropdown", false);
+    await mountStrip();
+    expect(strip()).toBeNull();
+  });
+
+  it("lists a menu only while it blocks as a mobile bottom sheet", async () => {
+    manager.register("modal", true, "Custom theme");
+    const popup = manager.register("dropdown", false, "Pick a color", true);
+    await mountStrip();
+    expect(labels()).toEqual(["Custom theme", "Pick a color"]);
+    // The sheet paints above the window, so it is the current crumb.
+    expect(
+      strip()!.querySelector(".hk-modal-breadcrumb-item-current")!.textContent,
+    ).toBe("Pick a color");
+
+    // Morphing back to an anchored popover (blocking=false) removes the
+    // level instead of leaving a stale crumb behind.
+    manager.setBlocking(popup.id, false);
+    await nextTick();
+    expect(strip()).toBeNull();
+  });
+
+  it("never falls back to a bare Layer N label", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      // Untitled window + untitled blocking sheet: the strip must use the
+      // localized generic labels ("Window" / "Menu" in en), not "Layer N".
+      manager.register("modal", true);
+      manager.register("dropdown", false, undefined, true);
+      await mountStrip();
+      expect(labels()).toEqual(["Window", "Menu"]);
+      expect(labels().join(" ")).not.toMatch(/Layer/);
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it("orders crumbs by z and names the strip for assistive tech", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const win = manager.register("modal", true, "Settings");
+      const drawer = manager.register("drawer", true, "Details");
+      expect(drawer.zIndex).toBeGreaterThan(win.zIndex); // same band, later slot
+      await mountStrip();
+      // In-band order is open order: the later drawer sits on top.
+      expect(labels()).toEqual(["Settings", "Details"]);
+      expect(strip()!.getAttribute("aria-label")).toBe("Window layers");
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it("exposes the registry entry shape the strip reads", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const handle = manager.register("dropdown", false, "Sheet", true);
+      const entry = manager.registry.value.get(handle.id);
+      expect(entry).toMatchObject({ kind: "dropdown", title: "Sheet", blocking: true });
+    } finally {
+      warn.mockRestore();
+    }
+  });
+});