@celestia-island/hikari 0.41.9 → 0.42.2

package/src/components/HkMinimap.toolbarOnly.test.tsx

@@ -0,0 +1,54 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h } from "vue";
+
+import HkMinimap from "./HkMinimap";
+
+const mounts: ReturnType<typeof createApp>[] = [];
+const containers: HTMLElement[] = [];
+
+afterEach(() => {
+  for (const app of mounts.splice(0)) app.unmount();
+  for (const el of containers.splice(0)) el.remove();
+});
+
+function mountMinimap(props: Record<string, unknown>): HTMLElement {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  containers.push(container);
+
+  const Host = defineComponent({
+    setup() {
+      return () => h("div", [h(HkMinimap, props)]);
+    },
+  });
+  const app = createApp(Host);
+  mounts.push(app);
+  app.mount(container);
+  return container;
+}
+
+describe("HkMinimap toolbar-only form", () => {
+  it("renders nothing without boxes, an image, or the toolbar-only flag", () => {
+    const c = mountMinimap({ zoomPercent: 100 });
+    expect(c.querySelector(".hk-minimap")).toBeNull();
+  });
+
+  it("renders only the zoom bar under toolbarOnly (no overview map)", () => {
+    const c = mountMinimap({ zoomPercent: 100, toolbarOnly: true });
+    const root = c.querySelector<HTMLElement>(".hk-minimap");
+    expect(root).not.toBeNull();
+    expect(root!.hasAttribute("data-toolbar-only")).toBe(true);
+    expect(root!.querySelector(".hk-minimap-svg")).toBeNull();
+    expect(root!.querySelector(".hk-mm-zoom-bar")).not.toBeNull();
+    expect(root!.querySelectorAll(".hk-mm-zoom-btn").length).toBe(2);
+  });
+
+  it("keeps the overview map when toolbarOnly is not set and an image is given", () => {
+    const c = mountMinimap({ imageSrc: "data:image/gif;base64,", toolbarOnly: false });
+    const root = c.querySelector<HTMLElement>(".hk-minimap");
+    expect(root).not.toBeNull();
+    expect(root!.hasAttribute("data-toolbar-only")).toBe(false);
+    expect(root!.querySelector(".hk-minimap-svg")).not.toBeNull();
+    expect(root!.querySelector(".hk-mm-zoom-bar")).not.toBeNull();
+  });
+});

package/src/components/HkMinimap.tsx

@@ -65,6 +65,12 @@ export default defineComponent({
     /** Show the reset/fit button in the zoom bar (chest only rendered it
      *  when a reset handler was wired up). */
     showReset: { type: Boolean, default: false },
+    /** Toolbar-only form: render just the zoom bar, no overview map. For
+     *  hosts whose viewport rect is uninformative at rest (e.g. the image
+     *  lightbox at fit zoom) but that still want the zoom controls
+     *  visible; the map is expected to reappear once it has something to
+     *  say (the viewer switches this off when zoomed past fit). */
+    toolbarOnly: { type: Boolean, default: false },
     /** Optional prop-callback surface (alternative to the emits). */
     onZoomTo: { type: Function as PropType<(percent: number) => void>, default: undefined },
     onReset: { type: Function as PropType<() => void>, default: undefined },
@@ -180,7 +186,7 @@ export default defineComponent({
     });
 
     return () => {
-      if (props.boxes.length === 0 && !props.imageSrc) return null;
+      if (props.boxes.length === 0 && !props.imageSrc && !props.toolbarOnly) return null;
 
       const s = scale.value;
       const vr = viewportRect.value;
@@ -213,42 +219,45 @@ export default defineComponent({
           ref={rootRef}
           class="hk-minimap"
           data-dragging={dragging.value ? "" : undefined}
+          data-toolbar-only={props.toolbarOnly ? "" : undefined}
         >
-          <svg viewBox={`0 0 ${svgW} ${svgH}`} width={svgW} height={svgH} class="hk-minimap-svg">
-            {imgPos && (
-              <image
-                href={props.imageSrc}
-                x={imgPos[0]}
-                y={imgPos[1]}
-                width={ib.w * s}
-                height={ib.h * s}
-                preserveAspectRatio="none"
-                class="hk-mm-image"
+          {!props.toolbarOnly && (
+            <svg viewBox={`0 0 ${svgW} ${svgH}`} width={svgW} height={svgH} class="hk-minimap-svg">
+              {imgPos && (
+                <image
+                  href={props.imageSrc}
+                  x={imgPos[0]}
+                  y={imgPos[1]}
+                  width={ib.w * s}
+                  height={ib.h * s}
+                  preserveAspectRatio="none"
+                  class="hk-mm-image"
+                />
+              )}
+              {boxRects}
+              {hubP && (
+                <circle
+                  cx={hubP[0]}
+                  cy={hubP[1]}
+                  r={3}
+                  fill="rgb(var(--color-primary))"
+                  filter="drop-shadow(0 0 2px rgb(var(--color-primary) / 0.6))"
+                />
+              )}
+              <rect
+                x={vr.x}
+                y={vr.y}
+                width={Math.max(1, vr.w)}
+                height={Math.max(1, vr.h)}
+                fill="none"
+                stroke="rgb(var(--color-primary))"
+                stroke-width="1"
+                stroke-dasharray="3 2"
+                rx="2"
+                opacity="0.85"
               />
-            )}
-            {boxRects}
-            {hubP && (
-              <circle
-                cx={hubP[0]}
-                cy={hubP[1]}
-                r={3}
-                fill="rgb(var(--color-primary))"
-                filter="drop-shadow(0 0 2px rgb(var(--color-primary) / 0.6))"
-              />
-            )}
-            <rect
-              x={vr.x}
-              y={vr.y}
-              width={Math.max(1, vr.w)}
-              height={Math.max(1, vr.h)}
-              fill="none"
-              stroke="rgb(var(--color-primary))"
-              stroke-width="1"
-              stroke-dasharray="3 2"
-              rx="2"
-              opacity="0.85"
-            />
-          </svg>
+            </svg>
+          )}
           <div class="hk-mm-zoom-bar">
             <button
               class="hk-mm-zoom-btn"

package/src/components/HkScrollContainer.test.ts

@@ -11,6 +11,8 @@ interface Mounted {
   instance: {
     refresh: () => void;
     getOverflow: () => { horizontal: string; vertical: string };
+    isNearEnd?: () => boolean;
+    recheck?: () => void;
   } | null;
 }
 
@@ -47,7 +49,7 @@ function mountScroller(props: Record<string, unknown> = {}, slotText = "content"
 /** happy-dom performs no layout, so scroll geometry is stubbed on the
  *  viewport instance (shadowing the prototype getters) before a
  *  refresh() pass re-senses the overflow. */
-function stubGeometry(el: HTMLElement, geom: { scrollWidth?: number; clientWidth?: number; scrollLeft?: number }) {
+function stubGeometry(el: HTMLElement, geom: { scrollWidth?: number; clientHeight?: number; clientWidth?: number; scrollLeft?: number; scrollHeight?: number; scrollTop?: number }) {
   const desc: PropertyDescriptorMap = {};
   for (const [key, value] of Object.entries(geom)) {
     desc[key] = { configurable: true, get: () => value };
@@ -158,3 +160,44 @@ describe("HkScrollContainer scrollbar reactivity", () => {
     expect(root.querySelectorAll(".hk-scrollbar-track").length).toBe(0);
   });
 });
+
+describe("HkScrollContainer approachEnd", () => {
+  /** Two awaited frames: scheduleFrame's scheduling rAF + the composable's
+   *  onceFrame initial sensing pass. */
+  async function flushFrames(): Promise<void> {
+    await new Promise<void>((r) => requestAnimationFrame(() => r()));
+    await new Promise<void>((r) => requestAnimationFrame(() => r()));
+  }
+
+  it("emits approachEnd for under-filled content and exposes isNearEnd", async () => {
+    const emissions: number[] = [];
+    const m = mountScroller({ approachEnd: true, onApproachEnd: () => emissions.push(1) });
+    // happy-dom has no layout; a real under-filled DOM reports the
+    // CSSOM clamp (scrollHeight == clientHeight), so stub THAT.
+    stubGeometry(m.viewport, { scrollHeight: 300, clientHeight: 300, scrollTop: 0 });
+    await flushFrames();
+    expect(emissions.length).toBe(1);
+    expect(m.instance?.isNearEnd?.()).toBe(true);
+  });
+
+  it("does not emit when the prop is off", async () => {
+    const emissions: number[] = [];
+    mountScroller({ onApproachEnd: () => emissions.push(1) });
+    await flushFrames();
+    expect(emissions.length).toBe(0);
+  });
+
+  it("exposes recheck and honours it at the container level", async () => {
+    const emissions: number[] = [];
+    const m = mountScroller({ approachEnd: true, onApproachEnd: () => emissions.push(1) });
+    stubGeometry(m.viewport, { scrollHeight: 300, clientHeight: 300, scrollTop: 0 });
+    await flushFrames();
+    expect(emissions.length).toBe(1);
+    // Pin recheck on the exposed surface: dropping it from expose() must
+    // fail here, not just at the composable level.
+    expect(typeof m.instance?.recheck).toBe("function");
+    m.instance?.recheck?.();
+    await flushFrames();
+    expect(emissions.length).toBe(2);
+  });
+});

package/src/components/HkScrollContainer.tsx

@@ -12,6 +12,7 @@ import {
 import { useI18n } from "../i18n/context";
 import "./HkScrollContainer.scss";
 import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "../composables/useOverlayScrollbar";
+import { useApproachEnd, type ApproachEndHandle } from "../composables/useApproachEnd";
 import { provideScrollWindow } from "../composables/useScrollWindow";
 import { scheduleFrame, notifyScrollStart, onceFrame, type AnimationHandle } from "../runtime/animationBus";
 import HFab from "./HkFab";
@@ -61,8 +62,25 @@ export default defineComponent({
      *  scrolled away from the bottom, float a small jump-back FAB that
      *  snaps to the latest content and re-arms follow. */
     followAffordance: { type: Boolean, default: false },
+    /** Additive opt-in: sense "the viewport is at/near the end of its
+     *  content" and emit `approachEnd` so the consumer can load the
+     *  next page of data (infinite/dynamic loading). The event fires on
+     *  zone entry and whenever the content geometry grows while still
+     *  in the zone — including every pass while the content does not
+     *  fill the viewport (CSSOM clamps scrollHeight there, so the
+     *  under-filled state always reports; that is what lets a consumer
+     *  auto-fill a first screen). Fire-and-dedup contract: guard the
+     *  handler with your own loading flag; when a load renders nothing
+     *  new (all filtered out downstream), call the exposed `recheck()`
+     *  to force the next emission. */
+    approachEnd: { type: Boolean, default: false },
+    /** Distance in px from the vertical end that still counts as
+     *  approaching (`approachEnd`). Read live, so runtime changes need
+     *  no remount. */
+    approachDistance: { type: Number, default: 160 },
   },
-  setup(props, { slots, expose }) {
+  emits: { approachEnd: () => true },
+  setup(props, { slots, expose, emit }) {
     const { t } = useI18n();
     const viewportRef = ref<HTMLElement>();
     let ro: ResizeObserver | null = null;
@@ -87,6 +105,31 @@ export default defineComponent({
     let followRO: ResizeObserver | null = null;
     const showAutoTag = computed(() => props.autoFollow && props.scrollbar && pinned.value);
 
+    // End-approach sensing (infinite loading): the composable owns the
+    // scroll/resize/mutation sensors; this component only owns the
+    // lifecycle and forwards the emission. `distance` is passed as a
+    // getter so runtime approachDistance changes need no restart.
+    const approachHandle = shallowRef<ApproachEndHandle | null>(null);
+
+    function startApproach() {
+      if (approachHandle.value) return;
+      approachHandle.value = useApproachEnd(
+        viewportRef as unknown as import("vue").Ref<HTMLElement | null>,
+        () => emit("approachEnd"),
+        { distance: () => props.approachDistance },
+      );
+    }
+
+    function stopApproach() {
+      approachHandle.value?.stop();
+      approachHandle.value = null;
+    }
+
+    watch(() => props.approachEnd, (on) => {
+      if (on) startApproach();
+      else stopApproach();
+    }, { flush: "post" });
+
     if (props.mode === "windowed") {
       provideScrollWindow(viewportRef as unknown as import("vue").Ref<HTMLElement | null>, props.overscanScreens);
     }
@@ -255,6 +298,8 @@ export default defineComponent({
         mountScrollbars();
       }
 
+      if (props.approachEnd) startApproach();
+
       vp.addEventListener("scroll", onScroll, { passive: true });
       vp.addEventListener("wheel", onWheel, { passive: false });
 
@@ -287,6 +332,7 @@ export default defineComponent({
       }
       overlay?.detach();
       overlay = null;
+      stopApproach();
       scheduled?.disconnect();
       settleHandle?.disconnect();
       settleHandle = null;
@@ -341,7 +387,22 @@ export default defineComponent({
       };
     }
 
-    expose({ scrollTo, scrollToElement, getScrollElement, getScrollTop, refresh, getOverflow });
+    /** True while the viewport sits within `approachDistance` of its
+     *  vertical end (only meaningful with `approachEnd`). */
+    function isNearEnd(): boolean {
+      return approachHandle.value?.isNearEnd() ?? false;
+    }
+
+    /** Force one end-approach sensing pass that ignores the
+     *  same-geometry dedup. Call after a load that may still leave the
+     *  content under-filled — while under-filled the sensor fires on
+     *  its own, but a consumer whose load rendered nothing new (all
+     *  filtered out downstream) needs this to keep the walk going. */
+    function recheck(): void {
+      approachHandle.value?.recheck();
+    }
+
+    expose({ scrollTo, scrollToElement, getScrollElement, getScrollTop, refresh, getOverflow, isNearEnd, recheck });
 
     return () => {
       const Tag = props.as as "div" | "section" | "nav" | "main" | "aside";

package/src/components/HkTag.test.tsx

@@ -0,0 +1,76 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h, type VNode } from "vue";
+
+import HkTag from "./HkTag";
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mountTag(props: Record<string, unknown> = {}, children?: () => VNode) {
+  const events = { close: 0 };
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({
+    render: () =>
+      h(
+        HkTag,
+        {
+          ...props,
+          onClose: () => {
+            events.close++;
+          },
+        },
+        children ? { default: children } : undefined,
+      ),
+  });
+  app.mount(container);
+  mounts.push({ app, container });
+  return { events, container };
+}
+
+afterEach(() => {
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+  document.body.innerHTML = "";
+});
+
+describe("HkTag", () => {
+  it("renders slot content without a close button by default", () => {
+    const { container } = mountTag({}, () => h("span", "Default"));
+    const tag = container.querySelector(".hk-tag")!;
+    expect(tag.textContent).toBe("Default");
+    expect(tag.querySelector(".hk-tag-close")).toBeNull();
+  });
+
+  it("closable renders the × which emits close", () => {
+    const { events, container } = mountTag({ closable: true }, () => h("span", "Closable"));
+    const close = container.querySelector<HTMLButtonElement>(".hk-tag-close")!;
+    expect(close).toBeTruthy();
+    // The pre-prop markup: an unlabeled button, exactly as before.
+    expect(close.hasAttribute("aria-label")).toBe(false);
+    close.click();
+    expect(events.close).toBe(1);
+  });
+
+  it("closeLabel names the close button for screen readers", () => {
+    const { events, container } = mountTag(
+      { closable: true, closeLabel: "Remove — News" },
+      () => h("span", "News"),
+    );
+    const close = container.querySelector<HTMLButtonElement>(".hk-tag-close")!;
+    expect(close.getAttribute("aria-label")).toBe("Remove — News");
+    close.click();
+    expect(events.close).toBe(1);
+  });
+
+  it("keeps the variant and size classes untouched", () => {
+    const { container } = mountTag(
+      { variant: "success", size: "sm", closable: true, closeLabel: "Remove" },
+      () => h("span", "Done"),
+    );
+    const tag = container.querySelector(".hk-tag")!;
+    expect(tag.classList.contains("hk-tag-success")).toBe(true);
+    expect(tag.classList.contains("hk-tag-sm")).toBe(true);
+  });
+});

package/src/components/HkTag.tsx

@@ -11,6 +11,13 @@ export default defineComponent({
     variant: { type: String as PropType<TagVariant>, default: "default" },
     size: { type: String as PropType<"sm" | "md">, default: "md" },
     closable: { type: Boolean, default: false },
+    /**
+     * Accessible name of the close button, rendered as its `aria-label`.
+     * Undefined (the default) renders exactly the pre-prop markup, so
+     * existing consumers are untouched; tag fields that can carry several
+     * chips side by side set it to name the entry each × removes.
+     */
+    closeLabel: { type: String, default: undefined },
   },
   emits: {
     close: () => true,
@@ -34,6 +41,7 @@ export default defineComponent({
           <button
             type="button"
             class="hk-tag-close"
+            aria-label={props.closeLabel}
             onClick={() => emit("close")}
           >
             <X size={12} />