@celestia-island/hikari 0.55.140 → 0.55.141

package/package.json

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

package/src/components/HkPillToggleGroup.scss

@@ -1,15 +1,69 @@
 /**
  * HkPillToggleGroup chrome — the segmented pill track. Ported from the
- * wowsp 水表查询 filter bar's option group, token for token: shared
+ * wowsp 水表查询 filter bar's option group (strip chrome and fade
+ * masks token-for-token; the pills keep their pointer cursor — the
+ * strip root carries the grab affordance): shared
  * chrome around per-option buttons, the active option carrying the
  * indicator tint directly (multi-select cannot use HkTabs — its sliding
- * indicator is radio semantics).
+ * indicator is radio semantics). The track is the ONE-LINE PANNABLE
+ * STRIP: overflow hides under edge fades (data-h-overflow masks, the
+ * HkScrollContainer contract) and pans by wheel / mouse drag / native
+ * touch (the machinery lives in useOptionStrip); phones relax back into
+ * a wrapping group (media query below — the sheet carries full width).
  */
 
 .hk-pill-group {
   display: flex;
-  flex-wrap: wrap;
+  flex-wrap: nowrap;
+  max-width: 100%;
   gap: var(--space-4, 4px);
+  overflow-x: auto;
+  overflow-y: hidden;
+  touch-action: pan-x;
+  scrollbar-width: none;
+  overscroll-behavior-x: contain;
+
+  &::-webkit-scrollbar {
+    display: none;
+  }
+
+  --hk-scroll-fade-size: var(--space-24);
+
+  &[data-h-overflow="end"] {
+    -webkit-mask-image: linear-gradient(to left, transparent 0, #000 var(--hk-scroll-fade-size));
+    mask-image: linear-gradient(to left, transparent 0, #000 var(--hk-scroll-fade-size));
+  }
+
+  &[data-h-overflow="start"] {
+    -webkit-mask-image: linear-gradient(to right, transparent 0, #000 var(--hk-scroll-fade-size));
+    mask-image: linear-gradient(to right, transparent 0, #000 var(--hk-scroll-fade-size));
+  }
+
+  &[data-h-overflow="both"] {
+    -webkit-mask-image: linear-gradient(
+      to right,
+      transparent 0,
+      #000 var(--hk-scroll-fade-size),
+      #000 calc(100% - var(--hk-scroll-fade-size)),
+      transparent 100%
+    );
+    mask-image: linear-gradient(
+      to right,
+      transparent 0,
+      #000 var(--hk-scroll-fade-size),
+      #000 calc(100% - var(--hk-scroll-fade-size)),
+      transparent 100%
+    );
+  }
+
+  /* The whole strip drags; clicks still toggle — the 5px pan threshold
+   * keeps plain clicks click-shaped. */
+  cursor: grab;
+
+  &[data-panning] {
+    cursor: grabbing;
+    user-select: none;
+  }
   padding: 2px;
   border-radius: var(--radius-sm);
   border: 1px solid rgb(var(--color-border) / 25%);
@@ -60,3 +114,16 @@
    * pressure would collapse them before the label felt it. */
   flex: 0 0 auto;
 }
+
+/* Phones: the sheet carries the full width, nothing pans there — the
+ * strip relaxes back into the wrapping group (the wowsp filter bar's
+ * rule; the fade masks and the grab affordance name interactions the
+ * track no longer has). */
+@media (max-width: 767px) {
+  .hk-pill-group {
+    flex-wrap: wrap;
+    overflow: visible;
+    touch-action: auto;
+    cursor: default;
+  }
+}

package/src/components/HkPillToggleGroup.test.tsx

@@ -111,4 +111,67 @@ describe("HkPillToggleGroup", () => {
     expect(pills[2].querySelector(".hk-pill-group-icon")).toBeNull();
     expect(pills[2].textContent?.trim()).toBe("Jk");
   });
+
+  it("strip wiring: a drag pans and swallows its trailing click — a plain click still toggles", async () => {
+    const toggled: string[] = [];
+    const c = mount(
+      h(HkPillToggleGroup, {
+        label: "P",
+        options: OPTIONS,
+        selected: new Set<string>(),
+        onToggle: (v: string) => toggled.push(v),
+      }),
+    );
+    const group = c.querySelector(".hk-pill-group")!;
+    const pill = c.querySelectorAll<HTMLButtonElement>(".hk-pill-group-pill")[0];
+
+    // Press on a pill, stray past the 5px threshold, release: the strip
+    // flags the pan and the trailing click is swallowed exactly once.
+    pill.dispatchEvent(
+      new PointerEvent("pointerdown", { bubbles: true, pointerType: "mouse", button: 0, clientX: 100, clientY: 50 }),
+    );
+    window.dispatchEvent(
+      new PointerEvent("pointermove", { pointerType: "mouse", clientX: 120, clientY: 52 }),
+    );
+    await Promise.resolve();
+    expect(group.hasAttribute("data-panning")).toBe(true);
+    window.dispatchEvent(new PointerEvent("pointerup", { pointerType: "mouse" }));
+    await Promise.resolve();
+    expect(group.hasAttribute("data-panning")).toBe(false);
+    pill.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await Promise.resolve();
+    expect(toggled, "the pan's trailing click must not toggle").toEqual([]);
+
+    // The NEXT plain click toggles normally — the swallow is one-shot.
+    pill.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await Promise.resolve();
+    expect(toggled).toEqual([OPTIONS[0].value]);
+  });
+
+  it("strip wiring: a sub-threshold press never pans and its click toggles", async () => {
+    const toggled: string[] = [];
+    const c = mount(
+      h(HkPillToggleGroup, {
+        label: "P",
+        options: OPTIONS,
+        selected: new Set<string>(),
+        onToggle: (v: string) => toggled.push(v),
+      }),
+    );
+    const group = c.querySelector(".hk-pill-group")!;
+    const pill = c.querySelectorAll<HTMLButtonElement>(".hk-pill-group-pill")[1];
+
+    pill.dispatchEvent(
+      new PointerEvent("pointerdown", { bubbles: true, pointerType: "mouse", button: 0, clientX: 100, clientY: 50 }),
+    );
+    window.dispatchEvent(
+      new PointerEvent("pointermove", { pointerType: "mouse", clientX: 103, clientY: 51 }),
+    );
+    await Promise.resolve();
+    expect(group.hasAttribute("data-panning"), "3px stays a click").toBe(false);
+    window.dispatchEvent(new PointerEvent("pointerup", { pointerType: "mouse" }));
+    pill.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await Promise.resolve();
+    expect(toggled).toEqual([OPTIONS[1].value]);
+  });
 });

package/src/components/HkPillToggleGroup.tsx

@@ -1,5 +1,6 @@
 import { defineComponent, h, type PropType, type VNode } from "vue";
 
+import { useOptionStrip } from "../composables/useOptionStrip";
 import "./HkPillToggleGroup.scss";
 
 /** One toggleable pill of the group. */
@@ -30,9 +31,13 @@ function resolveIcon(icon: unknown): VNode | null {
  * chrome around per-option toggle buttons, the active option carrying
  * the indicator tint directly (multi-select cannot use HkTabs — its
  * sliding indicator is radio semantics). Grammar ported from the wowsp
- * 水表查询 filter bar's option strip (2026-10-11), wrapping instead of
- * panning: hikari ships page-sized groups, and hosts with strip-scale
- * sets host their own panning track.
+ * 水表查询 filter bar's option strip (2026-10-11); the track is the
+ * ONE-LINE PANNABLE STRIP (same-day follow-up direction): overflow
+ * hides under edge fades and pans by wheel / mouse drag / native touch,
+ * exactly the 水表 popups' behavior — a wrapping track always measured
+ * ONE long line inside HkPopover's max-content panel and ran off-screen
+ * (wowsp #667). Phones relax back into a wrapping group (the sheet
+ * carries full width; nothing pans there) via the SCSS media query.
  *
  * Deliberately THIN (the host owns the set): `toggle(value)` reports one
  * pill toggled; the optional leading all-pill reports `all()` and the
@@ -60,8 +65,17 @@ export default defineComponent({
     all: () => true,
   },
   setup(props, { emit }) {
+    const { stripEl, panning, onPointerDown } = useOptionStrip();
+
     return () => (
-      <div class="hk-pill-group" role="group" aria-label={props.label}>
+      <div
+        ref={stripEl}
+        class="hk-pill-group"
+        role="group"
+        aria-label={props.label}
+        data-panning={panning.value || undefined}
+        onPointerdown={onPointerDown}
+      >
         {props.allLabel != null && (
           <button
             type="button"

package/src/composables/useOptionStrip.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  WHEEL_LINE_PX,
+  overflowSides,
+  panEngaged,
+  stripWheelDelta,
+} from "./useOptionStrip";
+
+describe("stripWheelDelta", () => {
+  it("lets a real horizontal wheel delta win over the vertical one", () => {
+    expect(stripWheelDelta(0, -120, 40)).toBe(-120);
+  });
+  it("translates a plain vertical notch onto the horizontal axis", () => {
+    expect(stripWheelDelta(0, 0, 80)).toBe(80);
+    expect(stripWheelDelta(0, 0, -80)).toBe(-80);
+  });
+  it("normalizes Firefox line mode to pixels per notch", () => {
+    expect(stripWheelDelta(1, 0, 3)).toBe(3 * WHEEL_LINE_PX);
+    expect(stripWheelDelta(1, -2, 0)).toBe(-2 * WHEEL_LINE_PX);
+  });
+});
+
+describe("panEngaged", () => {
+  it("engages at the threshold on EITHER axis", () => {
+    expect(panEngaged(5, 0, 5)).toBe(true);
+    expect(panEngaged(0, -5, 5)).toBe(true);
+    expect(panEngaged(4, 4, 5)).toBe(false);
+  });
+});
+
+describe("overflowSides", () => {
+  function fake(scrollWidth: number, clientWidth: number, scrollLeft: number): HTMLElement {
+    return { scrollWidth, clientWidth, scrollLeft } as unknown as HTMLElement;
+  }
+  it("reports none when the strip fits", () => {
+    expect(overflowSides(fake(100, 120, 0))).toBe("none");
+  });
+  it("reports the edges that still hide content (sub-pixel resting counts)", () => {
+    expect(overflowSides(fake(200, 100, 0))).toBe("end");
+    expect(overflowSides(fake(200, 100, 100))).toBe("start");
+    expect(overflowSides(fake(200, 100, 40))).toBe("both");
+    expect(overflowSides(fake(200, 100, 0.5))).toBe("end");
+  });
+});

package/src/composables/useOptionStrip.ts

@@ -0,0 +1,209 @@
+/**
+ * useOptionStrip — the one-line pannable option track behind
+ * HkPillToggleGroup's strip mode. Upstreamed from wowsp's optionStrip
+ * (the 水表 filter bar's nation popup and every FilterCategoryChip
+ * popup, 2026-10-11 direction: the pill groups must pan with edge
+ * fades, not wrap). One module owns:
+ *
+ *   - the wheel→horizontal pan rule (a real horizontal delta wins; a
+ *     vertical notch is translated onto the strip; Firefox line mode is
+ *     normalized — mirrors HkScrollContainer's wheel rule);
+ *   - the mouse drag-pan (pointer capture + the 5px click/pan threshold;
+ *     the click a pan leaves behind is swallowed exactly once, so panning
+ *     never toggles an option);
+ *   - the overflow-side sensing behind the edge fades: the strip mirrors
+ *     HkScrollContainer's `data-h-overflow` contract (which inline edges
+ *     still hide content), and the host SCSS turns the value into the
+ *     matching mask-image gradients.
+ *
+ * The track element itself stays owned by the host component (its
+ * classes and sheet-mode overrides live there); the composable only
+ * wires listeners while the element is mounted.
+ */
+import { onBeforeUnmount, ref, watch, type Ref } from "vue";
+
+/** Firefox line-height wheel mode (deltaMode 1): one notch reports ~3
+ *  lines, not pixels — normalized here so a notch pans a wheel-like
+ *  distance on every engine (40px/line, the classic WebKit line height).
+ *  Page mode (deltaMode 2, effectively extinct) passes through raw. */
+export const WHEEL_LINE_PX = 40;
+
+/** Horizontal pan distance for a wheel gesture over the strip: a real
+ *  horizontal wheel/trackpad swipe (deltaX — shift+wheel reports as
+ *  deltaX natively too) wins; a plain vertical wheel notch is translated
+ *  onto the horizontal axis instead. */
+export function stripWheelDelta(deltaMode: number, deltaX: number, deltaY: number): number {
+  const raw = deltaX !== 0 ? deltaX : deltaY;
+  return deltaMode === 1 ? raw * WHEEL_LINE_PX : raw;
+}
+
+/** Press→pan decision for the strip drag: once the pointer strays
+ *  ≥ threshold px on EITHER axis the press turns into a pan; below it the
+ *  gesture stays a click (and clicks must keep toggling options). */
+export function panEngaged(dx: number, dy: number, threshold: number): boolean {
+  return Math.abs(dx) >= threshold || Math.abs(dy) >= threshold;
+}
+
+/** Which inline edges of a strip still hide content — the value mirrored
+ *  onto the element as `data-h-overflow` (HkScrollContainer's contract;
+ *  the SCSS maps each value to its edge-fade mask). Sub-pixel scroll
+ *  offsets count as resting at the edge. RTL flips the visual sides; the
+ *  family ships LTR only. */
+export type OverflowSides = "none" | "start" | "end" | "both";
+
+export function overflowSides(el: HTMLElement): OverflowSides {
+  const max = el.scrollWidth - el.clientWidth;
+  if (max <= 0) return "none";
+  const EDGE_PX = 1;
+  const atStart = el.scrollLeft <= EDGE_PX;
+  const atEnd = max - el.scrollLeft <= EDGE_PX;
+  if (atStart && atEnd) return "none";
+  return atStart ? "end" : atEnd ? "start" : "both";
+}
+
+/** Wire one strip element with the pan + fade machinery. The host binds
+ *  `stripEl` (template ref), mirrors `panning` into `data-panning`, and
+ *  attaches `onPointerDown`; the non-passive wheel listener, the
+ *  capture-phase click swallow and the overflow sensing ride the ref
+ *  transitions here (a JSX onWheel prop is passive in some paths and
+ *  could not preventDefault, and JSX has no capture-phase click prop). */
+export function useOptionStrip() {
+  const stripEl: Ref<HTMLElement | null> = ref(null);
+  const panning = ref(false);
+  const PAN_THRESHOLD = 5;
+  let pressX = 0;
+  let pressY = 0;
+  let lastX = 0;
+  let armed = false;
+  /** Set when a gesture turned into a pan: the trailing click (and only
+   *  that one) must not toggle an option. */
+  let dragged = false;
+  let resizeObserver: ResizeObserver | null = null;
+  let mutationObserver: MutationObserver | null = null;
+
+  /** Re-read the overflow sides and mirror them onto the element. Fires
+   *  on scroll, on element resizes and on content mutations (options
+   *  re-rendering can change the track's scroll width). */
+  function sense() {
+    const el = stripEl.value;
+    if (!el) return;
+    const sides = overflowSides(el);
+    if (sides === "none") delete el.dataset.hOverflow;
+    else el.dataset.hOverflow = sides;
+  }
+
+  function onWheel(e: WheelEvent) {
+    const el = stripEl.value;
+    if (!el || el.scrollWidth <= el.clientWidth) return;
+    const delta = stripWheelDelta(e.deltaMode, e.deltaX, e.deltaY);
+    if (delta === 0) return;
+    const prev = el.scrollLeft;
+    el.scrollLeft += delta;
+    // A saturated edge lets the wheel keep scrolling the page behind.
+    if (el.scrollLeft !== prev) e.preventDefault();
+  }
+
+  function onPointerDown(e: PointerEvent) {
+    if (e.pointerType !== "mouse" || e.button !== 0) return;
+    // A pan released off-strip leaves no click behind; clear the stale
+    // swallow flag so this press's own click always lands.
+    dragged = false;
+    pressX = lastX = e.clientX;
+    pressY = e.clientY;
+    armed = false;
+    window.addEventListener("pointermove", onPointerMove);
+    window.addEventListener("pointerup", onPointerUp, { once: true });
+    window.addEventListener("pointercancel", onPointerCancel, { once: true });
+  }
+
+  function onPointerMove(e: PointerEvent) {
+    if (!armed) {
+      if (!panEngaged(e.clientX - pressX, e.clientY - pressY, PAN_THRESHOLD)) return;
+      // Engage: capture the pointer so the pan keeps tracking off-panel,
+      // flag the strip (grabbing cursor + selection off) and arm the
+      // one-shot click swallow — with capture held, the trailing click
+      // retargets to the strip anyway, never onto an option.
+      armed = true;
+      panning.value = true;
+      dragged = true;
+      stripEl.value?.setPointerCapture(e.pointerId);
+    }
+    e.preventDefault();
+    const el = stripEl.value;
+    if (!el) return;
+    el.scrollLeft -= e.clientX - lastX;
+    lastX = e.clientX;
+  }
+
+  function teardownPress() {
+    armed = false;
+    panning.value = false;
+    window.removeEventListener("pointermove", onPointerMove);
+  }
+
+  function onPointerUp() {
+    teardownPress();
+  }
+
+  function onPointerCancel() {
+    // A cancelled gesture never leaves a click — no swallow to hold.
+    dragged = false;
+    teardownPress();
+  }
+
+  /** The click a completed pan leaves behind must never toggle an
+   *  option: swallowed exactly once, capture phase (ahead of every
+   *  option handler). Plain clicks pass untouched. */
+  function onClickCapture(e: MouseEvent) {
+    if (!dragged) return;
+    dragged = false;
+    e.stopPropagation();
+  }
+
+  /** A host popup that closed before the pan's trailing click (window
+   *  blur mid-drag — pointerup lost) must not carry the swallow flag
+   *  into the reopened panel. */
+  function resetDragged() {
+    dragged = false;
+  }
+
+  watch(stripEl, (el, prev) => {
+    prev?.removeEventListener("wheel", onWheel);
+    prev?.removeEventListener("click", onClickCapture, true);
+    prev?.removeEventListener("scroll", sense);
+    resizeObserver?.disconnect();
+    resizeObserver = null;
+    mutationObserver?.disconnect();
+    mutationObserver = null;
+    if (el) {
+      el.addEventListener("wheel", onWheel, { passive: false });
+      el.addEventListener("click", onClickCapture, true);
+      el.addEventListener("scroll", sense, { passive: true });
+      if (typeof ResizeObserver !== "undefined") {
+        resizeObserver = new ResizeObserver(sense);
+        resizeObserver.observe(el);
+      }
+      if (typeof MutationObserver !== "undefined") {
+        mutationObserver = new MutationObserver(sense);
+        mutationObserver.observe(el, { childList: true, subtree: true });
+      }
+      sense();
+    }
+  });
+  onBeforeUnmount(() => {
+    teardownPress();
+    // Full listener teardown: a component unmounting mid-pan must not
+    // leave listeners behind on the strip element or the window's
+    // once-listeners unheld.
+    const el = stripEl.value;
+    el?.removeEventListener("wheel", onWheel);
+    el?.removeEventListener("click", onClickCapture, true);
+    el?.removeEventListener("scroll", sense);
+    window.removeEventListener("pointerup", onPointerUp);
+    window.removeEventListener("pointercancel", onPointerCancel);
+    resizeObserver?.disconnect();
+    mutationObserver?.disconnect();
+  });
+
+  return { stripEl, panning, onPointerDown, resetDragged };
+}