@celestia-island/hikari 0.55.155 → 0.55.156

package/package.json

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

package/src/components/HkInfiniteTail.scss

@@ -0,0 +1,17 @@
+.hk-infinite-tail-sentinel {
+  // The sentinel is a zero-visibility geometry probe: it must occupy a
+  // stable sliver of layout (height 1px) so the IntersectionObserver
+  // has a rect to intersect, while staying invisible in every theme.
+  display: block;
+  width: 100%;
+  height: 1px;
+  margin: 0;
+  pointer-events: none;
+}
+
+.hk-infinite-tail-loading {
+  // The skeleton tail rides the list's own rhythm — padding only, no
+  // border/background of its own, so the placeholders read as rows of
+  // the list that are about to exist rather than a separate block.
+  padding: var(--space-8, 0.5rem) 0 var(--space-12, 0.75rem);
+}

package/src/components/HkInfiniteTail.test.tsx

@@ -0,0 +1,155 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, ref, type App } from "vue";
+
+import { HkInfiniteTail } from "./HkInfiniteTail";
+
+type IOMock = {
+  observe: ReturnType<typeof vi.fn>;
+  disconnect: ReturnType<typeof vi.fn>;
+  callback: IntersectionObserverCallback;
+};
+
+const apps: App[] = [];
+const containers: HTMLElement[] = [];
+let originalIO: (typeof globalThis)["IntersectionObserver"];
+let originalRect: typeof HTMLElement.prototype.getBoundingClientRect;
+let ioInstances: IOMock[] = [];
+
+/** A capturing IntersectionObserver stub: records every instance so a
+ * test can synthesize intersections against the real sentinel. */
+class IntersectionObserverStub {
+  constructor(callback: IntersectionObserverCallback) {
+    const mock: IOMock = {
+      observe: vi.fn(),
+      disconnect: vi.fn(),
+      callback,
+    };
+    ioInstances.push(mock);
+    return (mock as unknown) as IntersectionObserverStub;
+  }
+  observe(): void {}
+  disconnect(): void {}
+}
+
+function mount(node: ReturnType<typeof h>) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({ render: () => node });
+  app.mount(container);
+  apps.push(app);
+  containers.push(container);
+  return container;
+}
+
+function rect(top: number, height: number): DOMRect {
+  return {
+    x: 0, y: top, top, left: 0, right: 100, bottom: top + height,
+    width: 100, height, toJSON: () => ({}),
+  } as DOMRect;
+}
+
+beforeEach(() => {
+  originalIO = (globalThis as { IntersectionObserver?: unknown }).IntersectionObserver as never;
+  ioInstances = [];
+  (globalThis as { IntersectionObserver?: unknown }).IntersectionObserver = IntersectionObserverStub;
+  originalRect = HTMLElement.prototype.getBoundingClientRect;
+});
+
+afterEach(() => {
+  for (const app of apps.splice(0)) app.unmount();
+  for (const el of containers.splice(0)) el.remove();
+  (globalThis as { IntersectionObserver?: unknown }).IntersectionObserver = originalIO;
+  HTMLElement.prototype.getBoundingClientRect = originalRect;
+});
+
+describe("HkInfiniteTail", () => {
+  it("loading renders the animated skeleton placeholders", () => {
+    const c = mount(h(HkInfiniteTail, { state: "loading", skeletonCount: 4 }));
+    const skeletons = c.querySelectorAll(".hk-skeleton");
+    expect(skeletons.length).toBe(4);
+    expect(c.querySelector('[role="status"]')).not.toBeNull();
+  });
+
+  it("end renders the reached-the-end note with the progress counter", () => {
+    const c = mount(h(HkInfiniteTail, { state: "end", shown: 19, total: 19 }));
+    expect(c.querySelector(".hk-load-more")!.getAttribute("data-state")).toBe("end");
+    expect(c.querySelector(".hk-load-more-count")!.textContent).toBe("19 / 19");
+    expect(c.textContent).toContain("You've reached the end");
+  });
+
+  it("idle + auto renders the invisible sentinel and observes it", async () => {
+    const c = mount(h(HkInfiniteTail, { state: "idle" }));
+    const sentinel = c.querySelector(".hk-infinite-tail-sentinel") as HTMLElement;
+    expect(sentinel).not.toBeNull();
+    // The ref watcher attaches the observer on the post-flush pass.
+    await new Promise((r) => setTimeout(r, 10));
+    expect(ioInstances.length).toBe(1);
+    expect(ioInstances[0].observe).toHaveBeenCalledTimes(1);
+  });
+
+  it("every intersecting observer callback emits (pacing is the machine's)", async () => {
+    const fired: number[] = [];
+    mount(h(HkInfiniteTail, { state: "idle", onLoadMore: () => fired.push(1) }));
+    await new Promise((r) => setTimeout(r, 10));
+    const { callback } = ioInstances[0];
+    const entry = { isIntersecting: true, target: {} } as unknown as IntersectionObserverEntry;
+    callback([entry], (null as unknown) as IntersectionObserver);
+    expect(fired.length).toBe(1);
+    // A second intersection (geometry changed) emits again — the tail
+    // never throttles; the state machine's busy guard paces the loop.
+    callback([entry], (null as unknown) as IntersectionObserver);
+    expect(fired.length).toBe(2);
+  });
+
+  it("loading does not emit and neither does end", () => {
+    const fired: number[] = [];
+    mount(h(HkInfiniteTail, { state: "loading", onLoadMore: () => fired.push(1) }));
+    mount(h(HkInfiniteTail, { state: "end", onLoadMore: () => fired.push(1) }));
+    expect(ioInstances.length).toBe(0); // neither state renders a sentinel
+    expect(fired.length).toBe(0);
+  });
+
+  it("re-entering idle re-checks the rect and keeps filling (auto-fill)", async () => {
+    const fired: number[] = [];
+    // Sentinel sits inside the viewport → the rect check must fire.
+    HTMLElement.prototype.getBoundingClientRect = function (this: HTMLElement) {
+      if (this.classList.contains("hk-infinite-tail-sentinel")) return rect(200, 1);
+      return originalRect.call(this);
+    };
+    // The transition the machine produces when a page lands while the
+    // tail is still on screen: loading → idle on the SAME component
+    // instance, with no observer event to carry it — the rect re-check
+    // is what keeps the fill going.
+    const state = ref<"loading" | "idle">("loading");
+    const Host = defineComponent({
+      setup() {
+        return () => h(HkInfiniteTail, { state: state.value, onLoadMore: () => fired.push(1) });
+      },
+    });
+    mount(h(Host));
+    expect(fired.length).toBe(0);
+    state.value = "idle";
+    await new Promise((r) => setTimeout(r, 30));
+    expect(fired.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it("manual mode loading morphs the button instead of skeleton rows", () => {
+    const c = mount(h(HkInfiniteTail, { state: "loading", auto: false }));
+    // No skeleton placeholders in manual mode — the button morphs.
+    expect(c.querySelectorAll(".hk-skeleton").length).toBe(0);
+    const note = c.querySelector(".hk-load-more")!;
+    expect(note.getAttribute("data-state")).toBe("loading");
+    expect(c.querySelector("button.hk-btn")!.textContent).toContain("Loading");
+  });
+
+  it("manual mode renders the load-more button instead of the sentinel", () => {
+    const fired: number[] = [];
+    const c = mount(h(HkInfiniteTail, { state: "idle", auto: false, onLoadMore: () => fired.push(1) }));
+    expect(c.querySelector(".hk-infinite-tail-sentinel")).toBeNull();
+    const button = c.querySelector("button.hk-btn") as HTMLButtonElement;
+    expect(button).not.toBeNull();
+    button.click();
+    expect(fired.length).toBe(1);
+    expect(ioInstances.length).toBe(0);
+  });
+});

package/src/components/HkInfiniteTail.tsx

@@ -0,0 +1,222 @@
+import { defineComponent, nextTick, onScopeDispose, ref, watch, type PropType } from "vue";
+
+import HSkeletonList from "./HkSkeletonList";
+import HkLoadMore from "./HkLoadMore";
+import "./HkInfiniteTail.scss";
+
+/**
+ * HkInfiniteTail — the DOM half of the infinite-list scaffold, mounted
+ * directly after the list body (inside whatever scroll viewport the
+ * host already uses; it never creates one). Paired with
+ * `useInfinitePages`, the page state machine.
+ *
+ * State derivation (bind EXACTLY this — a first-page load must read as
+ * `"loading"` too, or a short first page never auto-fills):
+ *
+ *     state = exhausted ? "end" : (loading || loadingMore) ? "loading" : "idle"
+ *
+ * - `"loading"` — a page is in flight: the animated skeleton
+ *   placeholder rows (HkSkeletonList) occupy the tail, so the list
+ *   reads as "more is arriving", not "the page ended". In manual mode
+ *   the load-more button morphs to its in-place spinner instead
+ *   (HkLoadMore's own loading contract).
+ * - `"end"` — the machine is exhausted: the muted end note (and the
+ *   shown/total progress counter when the host passes them).
+ * - `"idle"` — more exists, nothing in flight. With `auto` (default)
+ *   the invisible sentinel watches the viewport and emits `loadMore`
+ *   as it approaches; with `auto={false}` the explicit load-more
+ *   button (HkLoadMore) renders instead. NOTE: with `auto`, a tail
+ *   page failure retries in place every time the sentinel re-enters
+ *   view (the machine's error guard paces it to one attempt per
+ *   emission, no backoff) — hosts that want backoff map the error
+ *   state away from `"idle"` themselves.
+ *
+ * The sentinel observes the BROWSER viewport (IntersectionObserver,
+ * `rootMargin` lookahead), so it works inside any nested scroll
+ * container without knowing which ancestor scrolls. Intersection
+ * alone misses the "page landed but the tail is still on screen"
+ * case (the observer does not re-fire without a geometry change), so
+ * every `idle` entry re-checks the sentinel's rect on the next frame
+ * and keeps filling until the tail actually leaves the viewport — the
+ * auto-fill contract for short first screens.
+ */
+export const HkInfiniteTail = defineComponent({
+  name: "HkInfiniteTail",
+  props: {
+    /** `loading` — fetching a later page (skeleton); `end` — exhausted
+     * (end note); `idle` — more available, awaiting the sentinel. */
+    state: {
+      type: String as PropType<"idle" | "loading" | "end">,
+      default: "idle" as const,
+    },
+    /** Auto-load on approach (default). `false` renders the explicit
+     * load-more button instead of the invisible sentinel. */
+    auto: { type: Boolean, default: true },
+    /** Delivered item count (with `total`, the progress counter). */
+    shown: { type: Number, default: undefined },
+    /** Match count behind the windowed list. */
+    total: { type: Number, default: undefined },
+    /** Skeleton placeholder rows while a later page is in flight. */
+    skeletonCount: { type: Number, default: 3 },
+    /** Row height of the skeleton placeholders (match the host's row
+     * height so the tail does not jump when real rows land). */
+    skeletonItemHeight: { type: String, default: "40px" },
+    /** Viewport lookahead in px before the tail enters view (default
+     * 480 — about half a screen of runway). Live: a change re-observes
+     * the sentinel with the new margin (the rect path reads it live
+     * either way). */
+    lookahead: { type: Number, default: 480 },
+    /** Diagnostic hook: rendered as `data-label` on the (aria-hidden)
+     * sentinel — for tests and DOM inspection, NOT an a11y name (the
+     * sentinel is invisible geometry; the visible states carry their
+     * own accessible text). */
+    label: { type: String, default: undefined },
+  },
+  emits: {
+    loadMore: () => true,
+  },
+  setup(props, { emit }) {
+    const sentinelRef = ref<HTMLElement | null>(null);
+    let io: IntersectionObserver | null = null;
+    let rafHandle: number | null = null;
+    let stopped = false;
+
+    function maybeLoad(): void {
+      if (stopped) return;
+      if (props.state !== "idle") return;
+      emit("loadMore");
+    }
+
+    function sentinelInView(): boolean {
+      const el = sentinelRef.value;
+      if (!el) return false;
+      const rect = el.getBoundingClientRect();
+      if (rect.height === 0 && rect.width === 0) return false;
+      // Mirror the observer's lookahead: the zone extends `lookahead`
+      // px below the viewport bottom (and above the top, so a fast
+      // upward fling back into the zone also counts).
+      const vh = window.innerHeight || 0;
+      return rect.top <= vh + props.lookahead && rect.bottom >= -props.lookahead;
+    }
+
+    function scheduleRectCheck(): void {
+      if (stopped || rafHandle != null) return;
+      rafHandle = requestAnimationFrame(() => {
+        rafHandle = null;
+        if (stopped) return;
+        if (sentinelInView()) maybeLoad();
+      });
+    }
+
+    function observe(): void {
+      unobserve();
+      const el = sentinelRef.value;
+      if (!el || typeof IntersectionObserver === "undefined") return;
+      io = new IntersectionObserver(
+        (entries) => {
+          for (const entry of entries) {
+            if (entry.isIntersecting) maybeLoad();
+          }
+        },
+        { rootMargin: `${props.lookahead}px 0px ${props.lookahead}px 0px` },
+      );
+      io.observe(el);
+    }
+
+    function unobserve(): void {
+      io?.disconnect();
+      io = null;
+    }
+
+    // Sentinel mount/swap: attach the observer.
+    watch(sentinelRef, (el) => {
+      if (el && !stopped) observe();
+      else unobserve();
+    }, { flush: "post" });
+
+    // A live `lookahead` change re-observes with the new margin (the
+    // margin is baked into the observer at observe time; the rect path
+    // above already reads it live).
+    watch(
+      () => props.lookahead,
+      () => {
+        if (sentinelRef.value && !stopped) observe();
+      },
+    );
+
+    // Every transition INTO idle re-checks the geometry on the next
+    // frame: a page that landed while the sentinel stayed on screen
+    // produced no intersection change, but the list still needs its
+    // next window (auto-fill).
+    watch(
+      () => props.state,
+      (state, prev) => {
+        if (state === "idle" && prev !== "idle") {
+          void nextTick(scheduleRectCheck);
+        }
+      },
+    );
+
+    onScopeDispose(() => {
+      stopped = true;
+      unobserve();
+      if (rafHandle != null) cancelAnimationFrame(rafHandle);
+    });
+
+    return () => {
+      // Manual mode never renders the sentinel; the button is the
+      // affordance. The end note renders in both modes.
+      if (props.state === "end") {
+        return (
+          <HkLoadMore
+            state="end"
+            shown={props.shown}
+            total={props.total}
+          />
+        );
+      }
+      if (props.state === "loading") {
+        // Manual mode: the button morphs to its in-place spinner
+        // (HkLoadMore's advertised loading contract) instead of being
+        // replaced by skeletons — the affordance never disappears.
+        if (!props.auto) {
+          return (
+            <HkLoadMore
+              state="loading"
+              shown={props.shown}
+              total={props.total}
+            />
+          );
+        }
+        return (
+          <div class="hk-infinite-tail-loading" role="status" aria-live="polite">
+            <HSkeletonList
+              count={props.skeletonCount}
+              itemHeight={props.skeletonItemHeight}
+            />
+          </div>
+        );
+      }
+      if (!props.auto) {
+        return (
+          <HkLoadMore
+            state="idle"
+            shown={props.shown}
+            total={props.total}
+            onLoadMore={() => maybeLoad()}
+          />
+        );
+      }
+      return (
+        <div
+          ref={sentinelRef}
+          class="hk-infinite-tail-sentinel"
+          aria-hidden="true"
+          data-label={props.label}
+        />
+      );
+    };
+  },
+});
+
+export default HkInfiniteTail;

package/src/components/HkSearchTrigger.scss

@@ -0,0 +1,42 @@
+/**
+ * HkSearchTrigger chrome: the header icon button, its active-keyword
+ * dot and the panel body. Deliberately the SAME grammar as
+ * HkFilterTrigger.scss — filter and search are the two header
+ * affordances of every list page and must read as one family.
+ */
+
+.hk-search-trigger {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+}
+
+/* Active-keyword marker: the filter trigger's dot, verbatim — "this
+ * page is searched" reads exactly like "this page is filtered". */
+.hk-search-trigger-dot {
+  position: absolute;
+  top: 1px;
+  right: 1px;
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: rgb(var(--color-primary));
+  pointer-events: none;
+}
+
+.hk-search-trigger-body {
+  /* One field, bounded like the filter panel: wide enough for a
+   * phrase, narrow enough to stay anchored beside its trigger. */
+  min-width: 240px;
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-8, 0.5rem);
+}
+
+.hk-search-trigger-footer {
+  display: flex;
+  justify-content: flex-end;
+  padding-top: var(--space-8, 0.5rem);
+  border-top: 1px solid rgb(var(--color-border) / 10%);
+  margin-top: var(--space-8, 0.5rem);
+}

package/src/components/HkSearchTrigger.test.tsx

@@ -0,0 +1,158 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, h, ref, type App } from "vue";
+
+import HkSearchTrigger from "./HkSearchTrigger";
+
+const apps: App[] = [];
+const containers: HTMLElement[] = [];
+
+function mount(node: ReturnType<typeof h>) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({ render: () => node });
+  app.mount(container);
+  apps.push(app);
+  containers.push(container);
+  return container;
+}
+
+afterEach(() => {
+  for (const app of apps.splice(0)) app.unmount();
+  for (const el of containers.splice(0)) el.remove();
+  document.body.innerHTML = "";
+});
+
+function triggerButton(container: HTMLElement): HTMLButtonElement {
+  const btn = container.querySelector<HTMLButtonElement>("button[aria-haspopup='dialog']");
+  expect(btn).not.toBeNull();
+  return btn!;
+}
+
+function searchField(): HTMLInputElement | null {
+  return document.querySelector<HTMLInputElement>(".hk-search-input-field");
+}
+
+/** A host that actually BINDS the keyword two-way — the trigger's
+ * commit guard compares against `modelValue`, so a static prop would
+ * swallow every commit after the first (exactly the bug a v-model host
+ * never sees). */
+function mountBound(props: Record<string, unknown> = {}) {
+  const commits: string[] = [];
+  const state = ref("");
+  const Host = {
+    setup() {
+      return () =>
+        h(HkSearchTrigger, {
+          ...props,
+          modelValue: state.value,
+          "onUpdate:modelValue": (v: string) => {
+            state.value = v;
+            commits.push(v);
+          },
+        });
+    },
+  };
+  const c = mount(h(Host as never));
+  return { c, commits, state };
+}
+
+describe("HkSearchTrigger", () => {
+  it("renders the header-chrome trigger with an accessible name", () => {
+    const c = mount(h(HkSearchTrigger, { modelValue: "" }));
+    const btn = triggerButton(c);
+    expect(btn.getAttribute("aria-label")).toBe("Search");
+    expect(btn.getAttribute("aria-expanded")).toBe("false");
+    // No keyword → no active dot.
+    expect(c.querySelector(".hk-search-trigger-dot")).toBeNull();
+  });
+
+  it("an active keyword shows the dot", () => {
+    const c = mount(h(HkSearchTrigger, { modelValue: "stale" }));
+    expect(c.querySelector(".hk-search-trigger-dot")).not.toBeNull();
+  });
+
+  it("click opens the panel with the input focused", async () => {
+    const c = mount(h(HkSearchTrigger, { modelValue: "" }));
+    triggerButton(c).click();
+    await new Promise((r) => setTimeout(r, 20));
+    const input = searchField();
+    expect(input).not.toBeNull();
+    // The panel input receives focus on open.
+    expect(document.activeElement).toBe(input);
+  });
+
+  it("typing commits debounced; clearing commits immediately", async () => {
+    vi.useFakeTimers();
+    try {
+      const { c, commits } = mountBound({ debounce: 200 });
+      triggerButton(c).click();
+      await vi.advanceTimersByTimeAsync(10);
+      const input = searchField()!;
+      input.value = "al";
+      input.dispatchEvent(new Event("input"));
+      await vi.advanceTimersByTimeAsync(50);
+      expect(commits).toEqual([]);
+      await vi.advanceTimersByTimeAsync(200);
+      expect(commits).toEqual(["al"]);
+
+      // Clearing is immediate — no debounced dot-lag.
+      input.value = "";
+      input.dispatchEvent(new Event("input"));
+      expect(commits).toEqual(["al", ""]);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("drafts shorter than minLength never commit (panel edits are free)", async () => {
+    vi.useFakeTimers();
+    try {
+      const { c, commits } = mountBound({ minLength: 3, debounce: 50 });
+      triggerButton(c).click();
+      await vi.advanceTimersByTimeAsync(10);
+      const input = searchField()!;
+      input.value = "ab";
+      input.dispatchEvent(new Event("input"));
+      await vi.advanceTimersByTimeAsync(120);
+      expect(commits).toEqual([]);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("Enter commits immediately, skipping the debounce", async () => {
+    vi.useFakeTimers();
+    try {
+      const { c, commits } = mountBound({ debounce: 5000 });
+      triggerButton(c).click();
+      await vi.advanceTimersByTimeAsync(10);
+      const input = searchField()!;
+      input.value = "ledger";
+      input.dispatchEvent(new Event("input"));
+      input.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter" }));
+      expect(commits).toEqual(["ledger"]);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("a pending debounced commit lands even after the panel closes", async () => {
+    vi.useFakeTimers();
+    try {
+      const { c, commits } = mountBound({ debounce: 30_000 });
+      triggerButton(c).click();
+      await vi.advanceTimersByTimeAsync(10);
+      const input = searchField()!;
+      input.value = "gpu";
+      input.dispatchEvent(new Event("input"));
+      await vi.advanceTimersByTimeAsync(50);
+      expect(commits).toEqual([]);
+      // Close with the debounce still pending — the trigger flushes the
+      // draft (the popover tears the input, and its timer, down).
+      triggerButton(c).click();
+      expect(commits).toEqual(["gpu"]);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});