@celestia-island/hikari 0.55.20 → 0.55.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.20",
+  "version": "0.55.21",
   "private": false,
   "type": "module",
   "description": "Hikari Vue 3 component library — production-grade UI components based on shittim-chest design system",

package/src/components/HkScrollContainer.test.ts

@@ -248,3 +248,156 @@ describe("HkScrollContainer approachEnd", () => {
     expect(emissions.length).toBe(2);
   });
 });
+
+// ── Back-to-top signal (scroll parameter every template can hand to a
+// floating quick-action pad) — sensed on the container's own throttled
+// pass; HkWaterfall forwards these thresholds and mirrors the emit. ──
+describe("HkScrollContainer back-to-top signal", () => {
+  async function flushFrames(): Promise<void> {
+    await new Promise<void>((r) => requestAnimationFrame(() => r()));
+    await new Promise<void>((r) => requestAnimationFrame(() => r()));
+  }
+
+  it("emits update:backTopVisible with the SHOW/HIDE hysteresis band", async () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+
+    const emitted: boolean[] = [];
+    const instance = ref<{ backTopVisible?: boolean } | null>(null);
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HkScrollContainer, {
+            ref: instance as never,
+            backTopShow: 360,
+            backTopHide: 240,
+            "onUpdate:backTopVisible": (v: boolean) => emitted.push(v),
+          }, { default: () => h("span", "content") });
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+    const viewport = container.querySelector<HTMLElement>(".hk-scroll-container-viewport");
+    if (!viewport) throw new Error("no viewport");
+
+    const scrollTo = async (top: number) => {
+      stubGeometry(viewport, { scrollTop: top, scrollHeight: 5000, clientHeight: 400 });
+      viewport.dispatchEvent(new Event("scroll"));
+      await flushFrames();
+    };
+
+    await scrollTo(0);
+    expect(emitted).toEqual([]); // below: never emits
+    await scrollTo(300);
+    expect(emitted).toEqual([]); // inside the band, was hidden: stays hidden
+    await scrollTo(400);
+    expect(emitted).toEqual([true]); // past SHOW: emits true
+    emitted.length = 0;
+    await scrollTo(300);
+    expect(emitted).toEqual([]); // inside the band, was visible: stays visible
+    await scrollTo(200);
+    expect(emitted).toEqual([false]); // below HIDE: emits false
+    app.unmount();
+  });
+
+  it("exposes the sensed state as backTopVisible", async () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+    const instance = ref<{ backTopVisible?: boolean } | null>(null);
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HkScrollContainer, {
+            ref: instance as never,
+            backTopShow: 100,
+          }, { default: () => h("span", "content") });
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+    const viewport = container.querySelector<HTMLElement>(".hk-scroll-container-viewport");
+    if (!viewport) throw new Error("no viewport");
+
+    stubGeometry(viewport, { scrollTop: 500, scrollHeight: 5000, clientHeight: 400 });
+    viewport.dispatchEvent(new Event("scroll"));
+    await flushFrames();
+    expect(instance.value?.backTopVisible).toBe(true);
+
+    // Show-only mode hides at the SAME threshold it shows at: 50 < 100
+    // must read false (the hysteresis fallback `top > show` is what
+    // pins this — a mutant `top > 0` would keep it true here).
+    stubGeometry(viewport, { scrollTop: 50, scrollHeight: 5000, clientHeight: 400 });
+    viewport.dispatchEvent(new Event("scroll"));
+    await flushFrames();
+    expect(instance.value?.backTopVisible).toBe(false);
+
+    stubGeometry(viewport, { scrollTop: 0, scrollHeight: 5000, clientHeight: 400 });
+    viewport.dispatchEvent(new Event("scroll"));
+    await flushFrames();
+    expect(instance.value?.backTopVisible).toBe(false);
+    app.unmount();
+  });
+
+  it("re-senses immediately when the thresholds change at runtime", async () => {
+    // Live-read contract (same as approachDistance): toggling backTopShow
+    // after mount must emit without waiting for the next scroll event —
+    // a consumer that swaps thresholds while idle gets a truthful signal.
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+    const emitted: boolean[] = [];
+    const props = reactive({ backTopShow: undefined as number | undefined });
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HkScrollContainer, {
+            backTopShow: props.backTopShow,
+            "onUpdate:backTopVisible": (v: boolean) => emitted.push(v),
+          }, { default: () => h("span", "content") });
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+    const viewport = container.querySelector<HTMLElement>(".hk-scroll-container-viewport");
+    if (!viewport) throw new Error("no viewport");
+    stubGeometry(viewport, { scrollTop: 500, scrollHeight: 5000, clientHeight: 400 });
+    await flushFrames();
+    expect(emitted).toEqual([]); // inert while unset, geometry already past
+
+    props.backTopShow = 100;
+    await nextTick();
+    await flushFrames();
+    expect(emitted).toEqual([true]); // re-sensed without any scroll event
+    app.unmount();
+  });
+
+  it("never emits while backTopShow is unset", async () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+    const emitted: boolean[] = [];
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HkScrollContainer, {
+            "onUpdate:backTopVisible": (v: boolean) => emitted.push(v),
+          }, { default: () => h("span", "content") });
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+    const viewport = container.querySelector<HTMLElement>(".hk-scroll-container-viewport");
+    if (!viewport) throw new Error("no viewport");
+    stubGeometry(viewport, { scrollTop: 5000, scrollHeight: 5000, clientHeight: 400 });
+    viewport.dispatchEvent(new Event("scroll"));
+    await flushFrames();
+    expect(emitted).toEqual([]);
+    app.unmount();
+  });
+});

package/src/components/HkScrollContainer.tsx

@@ -85,8 +85,23 @@ export default defineComponent({
      *  scroll content dissolving at the dock's edge reads as
      *  intentional instead of a hard clip. */
     dockFade: { type: Boolean, default: true },
+    /** Back-to-top signal (scroll parameter every scrollable template
+     *  can hand to a floating quick-action pad): while set, the
+     *  container derives a visibility signal from its own throttled
+     *  scroll pass — visible once scrollTop passes SHOW px, hidden
+     *  again below HIDE px. The HIDE < SHOW hysteresis band stops the
+     *  signal from flickering when the user idles at one threshold.
+     *  Emits `update:backTopVisible` on change; inert (never emitted)
+     *  while unset. */
+    backTopShow: { type: Number, default: undefined },
+    /** Hide threshold of the hysteresis; only read when `backTopShow`
+     *  is also set. Without it the signal falls back to the single
+     *  `top > backTopShow` test. A misconfigured `backTopHide >=
+     *  backTopShow` degrades the same way (the show test wins first),
+     *  so the band only widens, never inverts. */
+    backTopHide: { type: Number, default: undefined },
   },
-  emits: { approachEnd: () => true },
+  emits: { approachEnd: () => true, "update:backTopVisible": (_v: boolean) => true },
   setup(props, { slots, expose, emit }) {
     const { t } = useI18n();
     const viewportRef = ref<HTMLElement>();
@@ -112,6 +127,12 @@ export default defineComponent({
 
     const pinned = ref(true);
     const FOLLOW_THRESHOLD = 24;
+
+    // Back-to-top visibility (see the backTopShow prop doc). Starts
+    // false and only ever changes through the sensed hysteresis below —
+    // the same semantics HkWaterfall shipped before the signal moved
+    // down to the shared scroll host.
+    const backTopVisible = ref(false);
     const autoFollowContent = shallowRef<HTMLElement | null>(null);
     let followRO: ResizeObserver | null = null;
     const showAutoTag = computed(() => props.autoFollow && props.scrollbar && pinned.value);
@@ -186,6 +207,13 @@ export default defineComponent({
       scheduleUpdate();
     }, { flush: "post" });
 
+    // Runtime threshold changes re-sense immediately (same live-read
+    // contract as approachDistance): without this, a backTopShow toggle
+    // after mount would emit nothing until the next scroll/resize.
+    watch(() => [props.backTopShow, props.backTopHide] as const, () => {
+      scheduleUpdate();
+    });
+
     /** Build the overlay tracks for the enabled axes (scrollbar on). */
     function mountScrollbars() {
       const vp = viewportRef.value;
@@ -261,6 +289,30 @@ export default defineComponent({
       const vp = viewportRef.value;
       if (!vp) return;
       senseOverflow(vp);
+      senseBackTop(vp);
+    }
+
+    /** Back-to-top hysteresis, derived on the same throttled pass as the
+     *  overflow sensing (scroll / resize / content resize / refresh) so
+     *  every scrollable template gets the signal for free — no consumer
+     *  installs a second scroll listener. */
+    function senseBackTop(vp: HTMLElement) {
+      if (props.backTopShow === undefined) return;
+      const top = vp.scrollTop;
+      const show = props.backTopShow;
+      const hide = props.backTopHide;
+      const next =
+        hide !== undefined
+          ? top > show
+            ? true
+            : top < hide
+              ? false
+              : backTopVisible.value
+          : top > show;
+      if (next !== backTopVisible.value) {
+        backTopVisible.value = next;
+        emit("update:backTopVisible", next);
+      }
     }
 
     /** Mirror the live scroll geometry onto the root element as
@@ -455,7 +507,7 @@ export default defineComponent({
       approachHandle.value?.recheck();
     }
 
-    expose({ scrollTo, scrollToElement, getScrollElement, getScrollTop, refresh, getOverflow, isNearEnd, recheck });
+    expose({ scrollTo, scrollToElement, getScrollElement, getScrollTop, refresh, getOverflow, isNearEnd, recheck, backTopVisible });
 
     return () => {
       const Tag = props.as as "div" | "section" | "nav" | "main" | "aside";

package/src/components/HkWaterfall.tsx

@@ -252,25 +252,11 @@ export default defineComponent({
     function recomputeActive() {
       scrollRaf = null;
       if (!scrollEl) return;
-      const top = scrollEl.scrollTop;
-
-      if (props.backTopShow !== undefined) {
-        const show = props.backTopShow;
-        const hide = props.backTopHide;
-        const next =
-          hide !== undefined
-            ? top > show
-              ? true
-              : top < hide
-                ? false
-                : backTopVisible.value
-            : top > show;
-        if (next !== backTopVisible.value) {
-          backTopVisible.value = next;
-          emit("update:backTopVisible", next);
-        }
-      }
-
+      // Back-to-top visibility is no longer derived here: the shared
+      // scroll host (HkScrollContainer) senses it on its own throttled
+      // pass and this view mirrors the host's signal (see the render
+      // wiring below) — one scroll pass, one source of truth, and every
+      // other scrollable template gets the same signal for free.
       const viewportTop = scrollEl.getBoundingClientRect().top;
       const attr = sectionAttribute.value;
       const sections = scrollEl.querySelectorAll<HTMLElement>(`[${attr}]`);
@@ -409,6 +395,18 @@ export default defineComponent({
           class="hk-waterfall-scroll"
           mode="windowed"
           overscanScreens={props.overscanScreens}
+          // Back-to-top sensing lives on the scroll host now; this view
+          // forwards the thresholds and mirrors the emitted signal so its
+          // own public contract (update:backTopVisible + exposed
+          // backTopVisible) is unchanged for consumers.
+          backTopShow={props.backTopShow}
+          backTopHide={props.backTopHide}
+          onUpdate:backTopVisible={(v: boolean) => {
+            if (v !== backTopVisible.value) {
+              backTopVisible.value = v;
+              emit("update:backTopVisible", v);
+            }
+          }}
         >
           {{
             default: () =>