@celestia-island/hikari 0.41.9 → 0.42.1

package/package.json

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

package/src/DemoApp.tsx

@@ -16,6 +16,7 @@ import {
   HSkeleton, HSkeletonList, HAvatar, HKbd, HDivider,
   HAlert, HEmptyState, HExpansionPanel,
   HTabs, HCard, HTable, HTimeline,
+  HScrollContainer, HLoadMore,
   HMediaSlider, HMediaPlayer, HImageViewer,
   HImagePreview,
   HZoomToolbar, HMinimap, HTrendChart,
@@ -197,6 +198,24 @@ export default defineComponent({
       syncZoom();
     }
 
+    // HLoadMore + HScrollContainer approachEnd — the canonical dynamic
+    // loading pair: the container emits `approachEnd` when the content
+    // end nears (including the initial under-filled pass), the demo
+    // "fetches" a page, and the indicator morphs button → spinner → end.
+    const pagedRows = ref(Array.from({ length: 10 }, (_, i) => `Row ${i + 1}`));
+    const pagedState = ref<"idle" | "loading" | "end">("idle");
+    function loadPagedRows() {
+      if (pagedState.value !== "idle") return;
+      pagedState.value = "loading";
+      setTimeout(() => {
+        pagedRows.value = [
+          ...pagedRows.value,
+          ...Array.from({ length: 10 }, (_, i) => `Row ${pagedRows.value.length + i + 1}`),
+        ];
+        pagedState.value = pagedRows.value.length >= 60 ? "end" : "idle";
+      }, 500);
+    }
+
     return () => (
       <div class="demo">
         <header class="demo-header">
@@ -225,6 +244,22 @@ export default defineComponent({
           </div>
         </section>
 
+        <section>
+          <h2>HScrollContainer + HLoadMore</h2>
+          <HScrollContainer
+            style={{ height: "320px" }}
+            approachEnd
+            onApproachEnd={loadPagedRows}
+          >
+            <div style={{ display: "flex", flexDirection: "column" }}>
+              {pagedRows.value.map((r) => (
+                <div key={r} style={{ padding: "6px 12px", borderBottom: "1px solid rgb(var(--color-muted, 108 108 108) / 18%)" }}>{r}</div>
+              ))}
+              <HLoadMore state={pagedState.value} shown={pagedRows.value.length} total={60} onLoadMore={loadPagedRows} />
+            </div>
+          </HScrollContainer>
+        </section>
+
         <section>
           <h2>HIconButton</h2>
           <div class="row">

package/src/components/HkLoadMore.scss

@@ -0,0 +1,53 @@
+/*
+ * HkLoadMore — the unified bottom indicator for dynamically loaded
+ * lists. Hairline rules flank the control so the indicator reads as
+ * "the list pauses here" rather than a stray button; everything is
+ * token-driven (no hardcoded colors) so themes restyle it for free.
+ */
+
+.hk-load-more {
+  display: flex;
+  align-items: center;
+  gap: var(--space-12);
+  padding: var(--space-12) 0;
+  color: rgb(var(--color-text-tertiary));
+}
+
+/* Hairline rules: transparent at the outer edge, muted towards the
+ * control; the end rule mirrors the gradient. */
+.hk-load-more-rule {
+  flex: 1;
+  height: 1px;
+  background: linear-gradient(to right, transparent, rgb(var(--color-muted) / 35%));
+}
+
+.hk-load-more-rule-end {
+  background: linear-gradient(to left, transparent, rgb(var(--color-muted) / 35%));
+}
+
+.hk-load-more-core {
+  flex: none;
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-10);
+}
+
+/* Delivery progress ("3 / 19"): mono, tabular so the digits don't
+ * shimmer while counting up. */
+.hk-load-more-count {
+  font-family: var(--font-mono);
+  font-size: var(--text-2xs);
+  font-variant-numeric: tabular-nums;
+  letter-spacing: 0.04em;
+  color: rgb(var(--color-text-tertiary));
+}
+
+.hk-load-more[data-state="loading"] .hk-load-more-count {
+  opacity: 0.6;
+}
+
+.hk-load-more-end {
+  font-size: var(--text-2xs);
+  letter-spacing: 0.08em;
+  color: rgb(var(--color-text-tertiary));
+}

package/src/components/HkLoadMore.test.tsx

@@ -0,0 +1,65 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h } from "vue";
+
+import HkLoadMore from "./HkLoadMore";
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mount(node: ReturnType<typeof h>) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({ render: () => node });
+  app.mount(container);
+  mounts.push({ app, container });
+  return container;
+}
+
+afterEach(() => {
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+});
+
+/** The en bundle loads eagerly, so the two-arg t() fallbacks double as
+ *  the assertions' expected strings — no i18n test setup needed. */
+describe("HkLoadMore", () => {
+  it("idle renders the load-more button and the shown/total counter", () => {
+    const c = mount(h(HkLoadMore, { shown: 3, total: 19 }));
+    const button = c.querySelector("button.hk-btn");
+    expect(button).not.toBeNull();
+    expect(button!.textContent).toContain("Load more");
+    expect(c.querySelector(".hk-load-more-count")!.textContent).toBe("3 / 19");
+    expect(c.querySelector(".hk-load-more")!.getAttribute("data-state")).toBe("idle");
+  });
+
+  it("clicking the button emits load-more", () => {
+    const fired: string[] = [];
+    const c = mount(h(HkLoadMore, { onLoadMore: () => fired.push("more") }));
+    (c.querySelector("button.hk-btn") as HTMLButtonElement).click();
+    expect(fired).toEqual(["more"]);
+  });
+
+  it("loading state disables the button with aria-busy and the loading label", () => {
+    const c = mount(h(HkLoadMore, { state: "loading", shown: 3, total: 19 }));
+    const button = c.querySelector("button.hk-btn") as HTMLButtonElement;
+    expect(button.disabled).toBe(true);
+    expect(button.getAttribute("aria-busy")).toBe("true");
+    expect(button.textContent).toContain("Loading…");
+    expect(c.querySelector(".hk-spinner")).not.toBeNull();
+  });
+
+  it("end state swaps the button for the reached-the-end status note", () => {
+    const c = mount(h(HkLoadMore, { state: "end", shown: 19, total: 19 }));
+    expect(c.querySelector("button.hk-btn")).toBeNull();
+    const note = c.querySelector('[role="status"]');
+    expect(note).not.toBeNull();
+    expect(note!.textContent).toContain("You've reached the end");
+    expect(c.querySelector(".hk-load-more-count")!.textContent).toBe("19 / 19");
+  });
+
+  it("omits the counter entirely when shown/total are absent", () => {
+    const c = mount(h(HkLoadMore));
+    expect(c.querySelector(".hk-load-more-count")).toBeNull();
+  });
+});

package/src/components/HkLoadMore.tsx

@@ -0,0 +1,72 @@
+import { defineComponent, type PropType } from "vue";
+
+import "./HkLoadMore.scss";
+import { useI18n } from "../i18n/context";
+import HButton from "./HkButton";
+
+/**
+ * The unified bottom indicator for dynamically loaded lists — one look
+ * for every consumer (cruise panels, tables, feeds), three states:
+ *
+ * - `idle`: a ghost load-more button; clicking emits `loadMore`.
+ * - `loading`: the SAME button with its built-in spinner (HkButton
+ *   swaps in an HSpinner while loading) — no second spinner here, the
+ *   affordance morphs in place at a stable height.
+ * - `end`: a muted "reached the end" note replacing the button.
+ *
+ * Optional `shown`/`total` render a tabular mono counter next to the
+ * control in every state ("3 / 19"), giving users the delivery
+ * progress without each app inventing its own wording.
+ */
+export default defineComponent({
+  name: "HkLoadMore",
+  props: {
+    state: { type: String as PropType<"idle" | "loading" | "end">, default: "idle" },
+    /** Delivered item count (with `total`, renders the progress counter). */
+    shown: { type: Number, default: undefined },
+    /** Full item count behind the windowed list. */
+    total: { type: Number, default: undefined },
+  },
+  emits: ["loadMore"],
+  setup(props, { emit }) {
+    const { t } = useI18n();
+    return () => {
+      const hasCount =
+        typeof props.shown === "number" && typeof props.total === "number";
+      const loading = props.state === "loading";
+      return (
+        <div class="hk-load-more" data-state={props.state}>
+          <span class="hk-load-more-rule" aria-hidden="true" />
+          <span class="hk-load-more-core">
+            {props.state === "end" ? (
+              <span class="hk-load-more-end" role="status">
+                {t("hikari::loadMore.end", "You've reached the end")}
+              </span>
+            ) : (
+              <HButton
+                variant="ghost"
+                size="sm"
+                icon="ChevronDown"
+                loading={loading}
+                aria-label={
+                  loading
+                    ? t("hikari::loadMore.loading", "Loading…")
+                    : t("hikari::loadMore.more", "Load more")
+                }
+                onClick={() => emit("loadMore")}
+              >
+                {loading
+                  ? t("hikari::loadMore.loading", "Loading…")
+                  : t("hikari::loadMore.more", "Load more")}
+              </HButton>
+            )}
+            {hasCount ? (
+              <span class="hk-load-more-count">{props.shown} / {props.total}</span>
+            ) : null}
+          </span>
+          <span class="hk-load-more-rule hk-load-more-rule-end" aria-hidden="true" />
+        </div>
+      );
+    };
+  },
+});

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} />